This section contains the following topics:
authxapi_RegisterExitFunction Function
authxapi_UnregisterExitFunction Function
authxapi_IsThereExitFunction Function
authxapi_GetObjectProperty Function
authxapi_GetObjectListValue Function
UserDefinedPrefix_RegisterExit Function
The Exits API lets you insert your own functions to be executed just before or after CA ControlMinder authorizes a requested activity. The seosd daemon/service monitors all system, program, and user activities. It intercepts every activity and decides whether to authorize the requested action. You can insert your own registered functions just before (pre) or after (post) CA ControlMinder makes these decisions.
For example, you can register a pre‑exit function for execution before CA ControlMinder considers each login request. Your exit function gains control just before CA ControlMinder starts to authorize a login request. After completing its task, your exit function returns control to CA ControlMinder with a return code indicating your function's authorization decision. Your function must return one of the following return codes:
Instructs CA ControlMinder to perform its own standard authorization check.
Instructs CA ControlMinder to grant the request. CA ControlMinder does not perform its own standard authorization check.
Instructs CA ControlMinder to deny the request. CA ControlMinder does not perform its own standard authorization check.
If the decision is SEOS_EXITR_PASS or SEOS_EXITR_DENY, CA ControlMinder grants or denies the request immediately. If it is SEOS_EXITR_CHECK, CA ControlMinder continues with its own standard authorization check. System, program, and user activities that require authorization by CA ControlMinder are called events. CA ControlMinder authorizes five categories of events:
New exit functions are added to the seosd and sepass programs by writing C‑language functions that can be compiled and linked to a shared library. The seos.ext and sepass.ext files must be changed to include this new, shared library.
An Exits API function has three parts:
The registration function initializes your Exits API function and registers it with the CA ControlMinder programs. The implementation function adds your tasks to the standard CA ControlMinder processing. The termination function unregisters and shuts your program down properly when the CA ControlMinder programs themselves terminate.
The following diagram illustrates the flow of the Exits API initialization, implementation, and termination functions in UNIX.
Your Exits API exit functions take advantage of functions and header files provided by CA ControlMinder. You use the same registration, initialization, and termination functions for all your exit functions, whether they link to seosd or sepass.
When your Exits API function is ready, you must link your new API to the CA ControlMinder daemons.
You add new exit functions to the sesudo and sesu programs by writing C‑language functions that can be compiled and linked to a shared library. You must change the *.ext files to include this new, shared library.
An Exits API function has three parts:
The registration function initializes your Exits API function and registers it with the utilities. The implementation function adds your tasks to the standard utilities' regular activities. The termination function unregisters and shuts your program down properly when the utilities themselves terminate.
Note: Examples for utility exits APIs are available in the following directory:
ACDir/apisamples
You add new exit functions to the seosd service and to pwdchange.dll by writing C-language functions that can be compiled and linked to a dynamic link library (dll). To install new exits, you must add new sub-keys under the following registry key:
HKEY_LOCAL_MACHINE\Software\ComputerAssociates\AccessControl\Exits\Engine
Exit APIs can fall into one of the following categories:
The registration function initializes your Exits API function and registers it with CA ControlMinder programs. The implementation function adds your tasks to the standard CA ControlMinder processing.
The following diagram illustrates the flow of the Exits API initialization and implementation.
Your Exits API exit functions take advantage of functions and header files provided by CA ControlMinder. You use the same registration and implementation functions for all your exit functions, whether they link to seosd or pwdchange.
When your Exits API function is ready, you must link your new API to the CA ControlMinder services.
All Exits API functions use special data structures provided by CA ControlMinder to pass information back and forth between functions. Programmers must know the specific formats and data types used by these structures to access them correctly in their own programs. The input data structure used by your exit function depends on the event being intercepted by the function. All functions use the same output data structure. The following table lists the data structures used by the Exits API functions.
|
Event |
Data Structure |
Type |
|---|---|---|
|
Login |
SEOS_EXITLOGIN |
Input |
|
General resource check |
SEOS_EXITGENR |
Input |
|
TCP/IP request (for UNIX only) |
SEOS_EXITINET |
Input |
|
Password quality check |
SEOS_EXITPASS |
Input |
|
All events |
SEOS_EXITRES |
Output |
If your Exits API function is successful, it should fill in the SEOS_EXITRES structure and return 0. When CA ControlMinder receives a return code of 0, CA ControlMinder checks the result field in the SEOS_EXITRES structure. If the SEOS_EXITRES value is Pass or Deny, it is acted on immediately, and CA ControlMinder does not execute its own authorization check. If the result is Check, CA ControlMinder continues with its own authorization check.
If your Exits API function fails, it should fill in the SEOS_EXITRES structure and return a nonzero error code. When CA ControlMinder receives a nonzero return code, it adds an entry to the error log file with the source file name and line number as they appear in the SEOS_EXITRES structure. The other values set in SEOS_EXITRES are ignored. CA ControlMinder then continues with its own authorization check.
This chapter provides two sample Exits API functions. These examples can help you get started with your own programs. The first example is a simple counter that intercepts every CA ControlMinder authorization call and keeps statistics on how often such calls are made. The second example adds a new restriction to the password authorization algorithm of CA ControlMinder. This exit function stops users from choosing the word password as their new password.
System, program, and user activities that require authorization by CA ControlMinder are called events. Events are grouped into five categories:
Exit functions for password quality check and password change events are linked to the password utility sepass in UNIX and the password dll pwdchange in Windows. Exit functions for login, general resource check, and TCP/IP request events are linked to seosd.
The following events are registered with seosd:
A login event occurs whenever a user attempts to log in to the system. All information relevant to the login attempt is passed to the API function. This information includes:
This information is passed to the Exits function in the SEOS_EXITLOGIN structure.
Note: Part of the login authorization process involves a check of whether the user is allowed to log in from the terminal from which the login request is received. If a general resource exit function is registered, that exit function is called as part of the login check.
A general resource check event occurs whenever CA ControlMinder checks the authorization for any system request except login and TCP/IP requests. All information relevant to the system request is passed to the API function. This information includes:
This information is passed to the function in the SEOS_EXITGENR structure.
In UNIX, a TCP/IP request event occurs whenever a remote host attempts to connect to the local host. In this case, no information is available on the specific user. All information relevant to the connection attempt is passed to the API function. This information includes the host address and name, the type of access requested, the name of the program involved, the port number, and the protocol code. The information is passed to the function in the structure SEOS_EXITINET.
The password quality check and password change events are registered with the password utility sepass. The Exits API data structure SEOS_EXITPASS is used to pass information about these events between functions.
A password quality check event occurs whenever a user attempts to enter a new user password. CA ControlMinder always calls the verify exits (both pre‑ and post‑). CA ControlMinder verifies the password using its built‑in features only when users replace their own passwords. All information relevant to the attempt to enter a new password is passed to the API function. This information includes the name of the user invoking the password utility; the name of the user whose password is being changed; the user's old password, if it exists; the user's new password; and the CA ControlMinder result. Results may be 0 (Okay) or 1 (Error). All the information is passed to the function in the structure SEOS_EXITPASS.
A password change event occurs whenever a user attempts to update an existing user password. All information relevant to the update attempt is passed to the API function. This information includes the name of the user invoking the password utility; the name of the user whose password is being changed; the user's new password; and both the CA ControlMinder and the system results. The information is passed to the function in the structure SEOS_EXITPASS.
The password quality check and password change events are registered with the password dll pwdchange. After installing these events in the registry, you must reboot in order to have proper registration. The Exits API data structure SEOS_EXITPASS is used to pass information about these events between functions.
|
Copyright © 2013 CA Technologies.
All rights reserved.
|
|