Authentication Types
5.15. AM-Service Support
ASIS provides the following various service routines to support common AM requirements:
• Terminal I/O
• Memory allocation
• Interactivity communication
• Error reporting
• Log entry writing
• Debugging
5.15.1. Terminal Output Services
Synopsis
serviceStatus terminalOutput(bufferDescriptor_t buffer,
int characterSet, solicitRequest_t inputSolicit);
serviceStatus tokenOutput(tokenDescriptor_t token, solicitRequest_t inputSol icit);
Description
The terminalOutput( ) function provides text output capability. The tokenOutput( ) function provides binary token/ticket output capability and assumes that the security protocol is implemented on the site network.
Authentication requests received through the authentication API are not interactive;
therefore, if the signonCategory in the ARCB is withoutTokenAuthAPI, the terminalOutput service may not be used. If an AM attempts terminalOutput or tokenOutput when the signonCategory in the ARCB is withoutTokenAuthAPI, a status of notAllowed is returned.
For terminalOutput( ), the buffer contains the text (up to 1,000 characters) to output to the terminal. The length of the text is in the size component of the buffer descriptor, and can be 0. The text is not necessarily ASCII, and need not be NULL terminated. The text must begin on a word boundary.
For tokenOutput( ), the token contains the token or ticket binary text (up to a thousand 8-bit bytes) to output to the terminal. It is the same token data structure defined for the ARCB (see 5.12.5). Normally the tokenType field should match what was presented on the initial ticket, if applicable.
SolicitRequest_t is an enumerator typedef whose defined values are noInput, solicitInput, and solicitBlankedInput. If a response from the terminal is desired, the terminalOutput function must be qualified by the solicitInput or solicitBlankedInput values and ASIS marks the current authentication as having a pending terminal input request.
Later, the AM returns a waitResponse status to ASIS and the AM is subsequently called with the responseReceived action when the input arrives. If the input does not arrive and the terminal times out, the terminateAuthentication action is sent by ASIS instead.
Regardless of the value of characterSet, the individual characters contain 8 bits. The most significant 9th bit of each quarter-word should be 0. This is also true for token output. See the following for additional information:
• A value of 0 in characterSet (meaning Fieldata) is the only value not allowed and
• A value of 4 in characterSet (meaning raw binary) is allowed, but the AM should use tokenOutput( ) and not terminalOutput( ) to send all binary messages.
• A value of 1 (meaning U.S. ASCII) is typical.
The output text is passed through ASIS and Exec unchanged to the communications driver. For both demand and TIP, the terminal is in scroll mode. Line lengths exceeding 80 characters cause line wrap and scroll up.
Returns
serviceStatus = One of the following:
• successful: the output was delivered by the Exec to SILAS.
• notSuccessful: the output failed (for example, hold on terminals in effect).
• rejected: the request was rejected due to caller error (illegal input solicit value, caller not a processor activity, Fieldata characterSet, and so forth).
• notAllowed: an attempt was made to send terminal output or token output when the signonCategory is withoutTokenAuthAPI.
Errors
This function is available only to ASIS processor activities that are handling
authentications. If called by any other activity when ASIS is in debug mode, an error abort occurs; otherwise, a rejected status is returned.
C Example
#include "global.h"
#include "service.h"
#include <string.h>
#define CHARSET 1 Example
char *text = "Welcome to our Super Secure 2200.";
bufferDescriptor_t bd = {strlen(text),(void*)text};
serviceStatus_t status = terminalOutput(bd, CHARSET, noInput);
if (status != successful) {...}
5.15.2. Get Buffer Service
Synopsis
serviceStatus getBuffer(size_t size, scope_t scope, unsigned short int AM, locality_t locality, bufferDescriptor **newBuf);
Description
ASIS manages all shared-memory allocation and provides the getBuffer service so that AMs may obtain space.
The AM must preserve its pointers to memory areas either in the AM authentication specific data area of the ARCB or in areas already pointed to from the AM initialization data area. When the AM is called with the initializeAM function, these pointers may also be captured in the AM initialization data area itself. For all subsequent AM calls, any modification to the contents of this area do not persist beyond or become visible outside the current taskID context.
The getBuffer function is qualified by the scope and locality parameters (described later). The status returned identifies the result as successful, notSuccessful, or rejected. See the following descriptions:
• If successful, a container of the requested size was obtained and a pointer is placed in a new buffer descriptor that is returned using a pointer passed with the function. ASIS creates both the buffer and the buffer descriptor.
• If notSuccessful, dynamic shared memory resources did not permit allocation of the container at this time.
• If rejected, an error condition exists (described later).
Size gives the size of the desired storage container in sizeof( ) units (bytes). This should not be confused with the .size component of the returned buffer descriptor, which is set to 0 by ASIS indicating that the buffer is empty. The .pointer component of the descriptor is the actual buffer pointer.
Scope_t is an enumerator typedef with the defined values (scopeAM and scopeTask) that define the life of the buffer. Potentially, scopeAM buffers last forever, but scopeTask buffers are released automatically by ASIS when the current task (for example, authentication) completes. A persistent activity may only request scopeAM.
The AM number (0 through 63) ties ownership of the buffer to the requesting AM. This is particularly important when the buffer’s scope is scopeAM. ASIS does not verify that the AM number is correct when scope is scopeTask. The AM designers must specify it correctly if they wish to benefit from the improved debugging, tracing, and buffer release controls it provides in a multi-AM ASIS configuration.
Locality_t is an enumerator typedef with the defined values activity, program, and application. It identifies the address tree visibility of the buffer that the AM wants.
For shared memory, program is normally the appropriate value to let all ASIS and AM activities access the buffer. Application is also provided, however, in case the AM
ASIS tracks the ownership of containers acquired using this function. The following owner categories are defined:
• taskID (selected by scopeTask)
• AM (selected by scopeAM)
• ASIS
AM persistent activities must specify scopeAM when requesting shared-memory containers. ASIS restricts, and in one case automates, release of these containers according to rules specified later.
Note that the AM authentication-specific data area cannot be used to carry over information from one authentication to another. Any pointers stored are lost when the authentication completes. Buffers whose containers were acquired with scopeAM must not be retained in this area.
The use of getBuffer is encouraged even for activity level storage, instead of malloc( ) or equivalent.
Returns
serviceStatus = One of the following:
• successful: the buffer was successfully obtained.
• notSuccessful: the request failed (for example, not enough free buffer memory).
• rejected: the request was rejected because of caller error (illegal scope or locality value, persistent activity specified scopeTask, and so forth).
Errors
If the getBuffer scope value is scopeTask and the request is not made by an ASIS processor activity, an error abort occurs if ASIS is in debug mode; otherwise, a rejected status is returned.
If the getBuffer scope, locality, or AM number value is invalid, an error abort occurs if ASIS is in debug mode; otherwise, a rejected status is returned.
C Example
#include "global.h"
#include "service.h"
#include <string.h>
extern unsigned short int AM;
bufferDescriptor_t **bdp = NULL;
serviceStatus_t status =
getBuffer(sizeof(thing),scopeTask,AM,program,&bdp);
if (status == successful) {
memcpy(bdp->pointer,&thing,sizeof(thing)); /* copy "thing" to buffer */
(*bdp).size = sizeof(thing);
}
else {...}
5.15.3. Release Buffer Service
Synopsis
serviceStatus releaseBuffer(bufferDescriptor *oldBuf, unsigned short int AM)
;
Description
If *oldBuf points to a descriptor for a buffer that currently exists, was previously allocated by a getBuffer request, and is owned by the caller (based at least partly on the supplied AM number), it is released and a successful status is returned. The oldBuf descriptor is updated by clearing its .size to 0 and its .pointer to NULL. If the container does not exist or the requester does not own it, an error condition exists (described later in this subsection). The oldBuf pointer must point to the actual buffer descriptor returned earlier by getBuffer and not to a copy of it.
Container ownership is established according to the following rules:
• ASIS is a co-owner of all containers acquired using the getBuffer function.
• An AM owns all containers that it acquired with the scopeAM scope.
• The taskID of an ASIS processor activity that is executing owns all containers acquired with the scopeTask scope.
When an ASIS task is finished, all containers associated with the taskID are automatically released. This automatic action cannot update associated bufferDescriptor variables or free standing pointers, if any.
Returns
serviceStatus = One of the following:
• successful: the buffer was released.
• rejected: the request was rejected because of caller error (caller does not own the buffer, buffer already released, no buffer at the location, and so forth).
Errors
If the buffer does not exist or the input buffer descriptor pointer does not point to a current and valid descriptor, ASIS aborts if it is in debug mode. If oldBuf is NULL, the call is ignored and ASIS returns a successful status to the caller; otherwise, a rejected status is returned.
If the buffer exists but the requester does not own it (task-id or AM number mismatch), or the input AM number is invalid (not in the range 0 through 63), ASIS aborts if it is in debug mode; otherwise, a rejected status is returned.
C Example
#include "global.h"
#include "service.h"
extern unsigned short int AM;
serviceStatus_t status = releaseBuffer(bdp, AM);
if (status != successful) {...}
5.15.4. Error Report Service
Synopsis
void reportError(abort_t error, int errorCode);
Description
Abort_t is an enumerator typedef whose values are errorAuthentication and errorAM.
For errorAuthentication, this function aborts the current authentication and the Exec terminates the session. It does not return to the AM, and may be called while the AM is nested in internal function calls. Normally, an AM must return control to ASIS by returning a status to the callAMi that entered it. In this function, ASIS assumes responsibility for cleaning up the processor activity’s states such as ALS, local memory dynamic allocation, return control stack (RCS), and so forth.
For errorAM, this function provides a means for an AM to cause ASIS to abort in a controlled manner. This enables the AM to act decisively when it encounters a situation where the integrity of its authentication process is in question. The function does not return to the AM, and may be called while the AM is nested in internal function calls. It may be called by AM persistent activities as well as by processor activities executing in the AM.
This function places diagnostic information, including the specified errorCode, in the ASIS print file and the system log.
Returns
This function does not return.
Errors
There are no ASIS error conditions for this function.
C Example
#include "global.h"
#include "service.h"
#define MISCELLANEOUS_ERROR 0101
reportError(errorAuthentication,MISCELLANEOUS_ERROR
);
5.15.5. Signal Event Service
Synopsis
serviceStatus signalEvent(task_t taskID);
Description
This function is available only to AM persistent activities. ASIS knows its processor activities and considers the use of this function by these activities an error condition.
This function releases an authentication from the waitEvent state. ASIS considers it an error condition if the target authentication is not in this wait state.
The parameter passed to the function is a taskID that identifies the authentication to be awakened. The returned status indicates success if the taskID is valid and the associated authentication is in a state to receive the notification. If either of these conditions is not met, the returned status indicates an error.
Returns
serviceStatus = One of the following:
• successful: the signal was delivered and the task is reawakened.
• notSuccessful: the signal was not delivered. The task is not in the waitEvent state.
• rejected: the request was rejected because of caller error (invalid taskID, task that does not belong to the calling AM, and so forth).
Errors
This function is available only to AM persistent activities. If it is called by any other activity (for example, a processor) when ASIS is in debug mode, an error abort occurs;
otherwise, an error status is returned.
If the authentication identified by taskID is not waiting for event notification as the result of the AM returning from an ASIS callAMi invocation with the waitResponse callReturnStatus, a notSuccessful status is returned and the event signal is discarded.
Assuming that this is the result of a timing window between the two activities and not due to a flaw in AM design, the persistent activity may simply call signalEvent again until successful.
C Example
#include "global.h"
#include "service.h"
extern task_t taskid;
signalEvent(taskid);
5.15.6. Write Log Service
Synopsis
serviceStatus_t writeLog(int type, int subtype, int version, void * type_spec, int length);
Description
This function provides an interface to write log entries to the system log.
Input
• type: log entry type; User Authentication log entries are in the 170XX range.
• subtype: subtype for the log entry.
• version: version of the log entry.
• type_spec: pointer to the type-specific portion of the log entry, that is, the portion after the log entry header.
• length: length of the log entry type-specific portion in bytes.
Returns
writeLog returns “successful” if the log entry was written or “notSuccessful” in the event of errors.
C Example
#include "global.h"
#include "service.h"
#include "log17008.h"
logType17008_t logbuf;
serviceStatus_t logstatus;
/* Fill in log buffer */
logstatus = writeLog(pwChgLogEntry, SubType17008, ver17008, &logbuf,len17008);
5.15.7. Trace Level Service
Synopsis
int getTraceLevel(void);
Description
This function retrieves the current trace level for an AM. This allows an AM to do more selective tracing than the global traceMode flag supplied in the ARCB.
Returns
getTraceLevel() returns the current trace level in effect (0 - 15).
C Example
#include "global.h"
#include "service.h"
if (getTraceLevel() > 14) {
/* Display sensitive trace information */
}
5.15.8. Service Interface Summary
The five services are separate C functions and all return status as an integer value (0 means success) that is an enumerated type defined as serviceStatus_t. Parameters passed to the service interface vary by function as listed in Table 5–15.
Table 5–15. Service Interface Summary
Function Activity Type Returns Parameters Input by AM terminalOutput( ) Processor successful (0)
notSuccessful (1) rejected (2)
• Output buffer
• Output character set code
• Input solicit {noInput, solicitInput,
solicitBlankedInput}
tokenOutput( ) Processor successful (0) notSuccessful (1) rejected (2)
• Token buffer
• InputSolicit {noInput, solicitInput,
solicitBlankedInput}
Table 5–15. Service Interface Summary
Function Activity Type Returns Parameters Input by AM getBuffer( ) Any type, but
• Locality (activity, program, application)
• Place to return acquired buffer descriptor releaseBuffer( ) Any type successful (0)
rejected (2) • Buffer to release
• AM number (0–63) reportError( ) Any type, but
persistent signalEvent( ) Persistent successful (0)
notSuccessful (1) rejected (2)
TaskID
writeLog( ) Any type successful (0)
notSuccessful (1) • Log entry type
• Log entry subtype
• Log entry version
• Log entry type-specific data pointer
• Type-specific data length getTraceLevel( ) Any type Current trace
level in effect (0 - 15)
None
Data items of type bufferDescriptor are a structure whose components are a pointer (void*) and a data size (size_t). Data size is different than container size. It is initially 0 on output from getBuffer and is ignored on input to releaseBuffer.
Exact names of data types and items is defined by the SERVICE/H C header file provided with ASIS for use by AM developers. Types listed above are for illustrative purposes only.