AM Initialization Task

Synopsis

callReturnStatus initializeAMi(struct AICB * pAICB);

Description

During initialization, ASIS calls each of the 64 initializeAMi functions (in the order i = 0,1,2,...,63). See 5.4 for additional information. For this function, pAICB points to a structure referred to as the AM Initialization Context Block (AICB). In this structure, ASIS specifies the maximum number (never less than 10) of persistent activities that the AM can create for itself. (This number is fixed at 10.)

The persistent activities that the AM creates must not take actions that could result in the Exec receiving authentication-initiation input requiring ASIS processing until the AM receives the startAM function.

An AM can create more than the specified maximum number of persistent activities, but this risks reducing ASIS performance or causing a PCT abort. An abort is possible because ASIS determines the number of activities it will create both on the basis of system configuration information and its expectation of the maximum number of activities that AMs will create.

Note: The initializeAM call is made by an ASIS processor activity. This activity should not be held on test-and-set queues or for other indefinite duration

conditions. The activity associated with this call may interact with AM persistent activities in a general manner.

ASIS expects the AM to return information in the Modifiable Area of the AICB. Except as noted, all space is preallocated by ASIS. Unless specifically authorized, AMs must not retain pointers to space allocated by ASIS (as opposed to space allocated by ASIS on behalf of an AM request), because the information allocated by ASIS may be relocated in memory between AM calls.

This structure is defined as AICB in AM/H. The AICB is organized into a fixed area (AM can only read) and a modifiable area (AM may read and write) as listed in Table 5–2 and Table 5–3.

Table 5–2. AICB Fixed Data

Flag Array Description

int version AICB version; currently 0. This is the lowest AICB version supported by ASIS. See highestAICBVersionASIS in Table 5–3.

bool debugMode TRUE if debug mode (see 5.16) was in effect when ASIS created this context block.

bool traceMode TRUE if tracing mode (see 5.16) was in effect when ASIS created this context block.

bool singleMode TRUE if single-thread mode (see 5.16) was in effect when ASIS created this context block.

int persistentBudget The most persistent activities the AM can create. Guaranteed to be at least 10. The AM exceeds this budget at the risk of ASIS PCT

overflows.

Table 5–3. AICB Modifiable Data

Flag Array Description

char AMName[ ] Symbolic name (12-character, NULL-terminated ASCII) for this AM. NULL string allowed. Non-NULL name is

displayed by ASIS through its administrative interface. AM designers must make this name unique at their site, although duplicate names between AMs are allowed.

Initialized to NULL string by ASIS.

bufferDescriptor_t AMInitData Describes a buffer (possibly obtained with the getBuffer service) containing data that the AM requires ASIS to send back to it on every authentication. Only a copy is sent.

ASIS copies this buffer to a private location and never uses it again. Descriptor is initialized to NULL by ASIS, and may be left NULL.

size_t AMDataSize Size of a scratch buffer that the AM requires ASIS to obtain for it on each authentication. This is initialized to 0 by ASIS, and may be left 0 if no buffer is wanted.

int persistentActs Number of persistent activities the AM created, or the maximum number it expects to create later (whichever is higher). Initialized to 0 by ASIS. See persistentBudget in Table 5–2.

enum AMAssign_t

typeArray[ ] Array indexed by authentication type. ASIS initializes all entries to no. AM sets entries to yes for the types it can handle. Values are yes, no, and overridden but, AM only uses yes. The overridden value is not used in the AICB.

See a description of ASCB in 5.11.2.

Table 5–3. AICB Modifiable Data

Flag Array Description

char nameArray[ ][ ] Array of symbolic names (12-character, NULL-terminated ASCII) for authentication types whose corresponding typeArray entry is yes. NULL string allowed. Non-NULL identifier is displayed through administrative interface.

Authentication type is the first array dimension. Initialized to NULL strings by ASIS.

size_t defaultADA[ ] If this value is 0, ADA areas are not allocated for authentication requests delivered to the AM.

If this value is not 0 and an ADA already exists in the user-id record, the ADA is delivered to the AM.

If no ADA exists, a maximum size blank ADA buffer is provided. If the buffer is modified and the updatedADA flag is set in the ARCB on the AM response, a new ADA is created for the user-id with the new data.

The default ADA length table is no longer used. This data, if supplied, is for information only.

bool serializeUserID[ ] Array of indicators indexed by authentication type, all entries initialized to false by ASIS. AM sets entries to true for those authentication types for which it processes only one authentication at a time for each user-id. Different user-ids of the same authentication type can be authenticated concurrently. The AM must serialize any type for which it may update users’ ADAs.

bool contingencyNotify Set to true by the AM if it can receive synchronous contingencies taken by processor activities executing its code. Initialized to false by ASIS. See 5.11.4.

bool useridFromToken Set to true by the AM if it can receive the returnUID requestAction for sign-ons associated with a token or ticket. If set to false, the AM never receives

authentications with token/ticket. Initialized to false by ASIS.

bool useridFromSolicit Set to true by the AM if it can receive the returnUID requestAction for sign-ons associated with a ELMS message solicit response. If set to false, the AM never receives authentications with a solicit response. Initialized to false by ASIS.

bool useridForTIPOutput Set to true by the AM if it can receive the returnUID requestAction for sign-ons associated with TIP output-only. If set to false, the AM never receives

authentications for AUTOVALIDATE terminals. Initialized to false by ASIS.

int highestAICBVersionASIS The highest AICB version supported by ASIS. It is in the modifiable AI area only so it could be added at the end, making it unnecessary for existing AMs to recompile. The highest version currently supported by ASIS is version 1.

Table 5–3. AICB Modifiable Data

Flag Array Description

int lowestAICBVersionAM The lowest AICB version supported by the AM. It is initialized by ASIS to 0. It may be changed by an AM to reflect the lowest AICB version it wishes to support.

int highestAICBVersionAM The highest AICB version supported by the AM. It is initialized by ASIS to 0. It should be set by the AM to the highest version it supports to inform ASIS.

bool useridFromAuthUser Set to true by the AM if the AM can supply a user-id for an AUTH_USER API call. This field is recognized by ASIS only if the AM specifies it supports AICB version 1 by setting highestAICBVersionAM to 1 or greater.

When more than one AM requests responsibility for a specific authentication type code, the last one to make a request actually receives it. As discussed in 5.11.2, when an AM is called with the startAM function, it is passed a copy (possibly revised) of typeArray identifying the authentication type codes for which it has actually received responsibility.

Note: ASIS does nothing to prevent the AM from requesting traditional Exec users (authentication type 0) sign-ons by setting typeArray[0] =yes, but AM handling of these users is not supported.

As discussed in 5.11.4, an AM can request a write-back of the ADA to the user-id record after completing authentication. If this occurs under any circumstance other than for ADA initialization, the AM must indicate in response to this initializeAM call a requirement for authentication serialization on a user-id basis. Note that if serialization is not requested and ADA initialization is supported by the AM, multiple initializations can occur because of concurrent authentications. ASIS assumes that this is not a problem because (by implication) the same data is written each time. ADA write-back is not done for authentications that use the deferredUID method.

More than one AM may indicate the ability to supply a user-id for the with

token/ticket, without token/ticket (in other words, solicit-response), or TIP output-only authentication request category. When this occurs, these AMs are polled in

succession (largest i first, see 5.4) whenever that category of authentication request is received by ASIS. The authentication process is assigned to the first AM to return either a deferredUID or a user-id that exists and that has an authentication type for which the AM has received responsibility.

The AM initialization data bufferDescriptor AMInitData (if the .pointer component is not NULL) identifies a container providing AM-specific constant information that is required for all authentication processing. The AM must set the buffer descriptor’s .size component to indicate how many bytes of data are present. The container may include pointers to other shared memory containers with AM scope acquired by the AM during AM initialization. As an example, these containers might be used for communication with AM persistent activities.

ASIS includes a buffer containing a copy of this information as part of the data passed on every subsequent call to the AM. The original buffer is never used again by ASIS.

The AM authentication specific data area size AMDataSize (if not 0) characterizes a container in which data developed by the AM for a single authentication may be carried across multiple calls to the AM. ASIS includes a buffer with a container of that size as part of the data passed on subsequent AM calls related to an authentication task.

Returns

callReturnStatus=

goAM: The AM linked to the ith entry point is active.

omitAM: The AM linked to the ith entry point is inactive.

failAM: The AM linked to the ith entry point wants ASIS to abort.

If the AM returns the omitAM status, ASIS does not call that AM again under any circumstances.

Errors

If the AM returns invalid status for this function, ASIS aborts whether or not it is in debug mode.

If the AM returns the goAM status and cannot supply a user-id for at least one of the three authentication request categories, ASIS aborts if it is in debug mode; otherwise, when ASIS calls the AM with the startAM function, typesQualifier is set to noTypes and all typeArray entries to overridden.