NAME

catgen - generic high level functions

DESCRIPTION

This is the most important interface for the development of ``normal'' Agents.

The catgen interface is both platform and transport layer independent. Furthermore, it can determine the type of connection, the type of authentication and encryption, and perform logging to different systems in a uniform way.

The functions in this library are layered above a large number of low-level functions to provide a simple and powerful way to write Agents.

Perhaps the most important function in the catgen layer is the catgen_server() function. This is the function that will initialize the catgen layer, handle the task of listening to sockets, create threads or processes for incoming connections, and interpret the command line arguments supplied when starting the Agent.

The use of catgen_server() is encouraged although the same functionality can be achieved by explicitly calling a number of other functions.

Command Line Arguments

The command line arguments that affect the operation of an Agent are handled by catgen_server() (or catgen_parseargs). The use of catgen_getopt means that additional options can be used.

The options that must be supported in order for an Agent to work with the Agent control server, catd, are:

-R root
UNIX only. Specify registry root. This is the directory where the ``global.cfg'' file is located. The contents of global.cfg is loaded into ``Gen.RegRoot''. On Windows NT, a hard-coded default location in the registry is used.

-S server
Server to connect to (tcp:host:port). Overrides data from the registry. Mainly used when the Windows NT bindhook module forces servers to use dynamic ports. Stored in ``Gen.Override.Server''.

-D debugspec
Debug specification. A list of elements separated by ``;''. Elements may be:

  0-9           - set debug level 0-9 [default 0]
  >file         - append output to a file
  +t            - add a timestamp
  =prefix       - prefix specification, see caterr_setprefix(3)
  label         - select label(s)
  !label        - deselect label(s)

See caterr_setdebug().

-C
The Agent is under the control of the server process and should read commands from the specified encoded handle. The handle is a HANDLE in hexadecimal on Windows NT and a file descriptor in decimal, usually 0, on UNIX. Used by the control server. Sets ``Gen.HasParent'' to ``1''.

-P portspec [ @ sockspec ]
The port to listen to (usually tcp::port). The ``sockspec'' part is used only when an already open socket is passed to the Agent by the controlling process. The sockspec part can be converted to a socket using catsock_fromstring. For each session, ``.Sessions.<id>.PortSpec'' will contain its port specification.

Event Logging

The catgen layer has a number of predefined log messages that will be used if the info value ``log.facilityfile'' is not present. These can be used directly through the catgen interface by invoking the catgen_log() function.

The catgen layer has the facility label ``CONAGT'' and the facility code 800.

If an ELS server is to accept logs, a log specification file must be imported to the ELS server (see catgen_loadloglabels). The predefined catgen log messages are already present in the ELS server on the Keon Security Server. Hence, importing a log specification is not necessary as long as only the catgen default messages are used. See catgen_log for a description of the labels.

catgen info structure

catgen_init() (normally called indirectly via catgen_server()) installs the following nodes:

.Gen
Miscellaneous library information.

.Gen.Override
This node is installed first in every session search path to make it possible to override certain values. Data from the command line is installed here.

.Sessions
Each new session will get its own node here. Sessions have a numeric id.

.Services
Set up to auto-load from configuration data for each service.

.Tcp
Set up to auto-load from configuration data for each port.

When sessions are created, they will be given a standard search path (see catinfo), which has the following appearance:

 .Gen.Override, .Sessions.<id>, .Tcp.s<port> .Services.<service>, .Global

Hence, data from the command line takes precedence, followed by the (server side) port, followed by any service-specific data, and finally, the global defaults.

In locations where the connection is undefined, the search path does not include the ``Tcp'' or ``Sessions'' parts.

FUNCTION OVERVIEW

catgen_certerrtologid
Map a certificate error to the appropriate catgen log code.

catgen_checkauth
Check a user's access rights irrespective of whether the user logged in using the SSL or DASP authentication scheme. This function can be called only after a successful SSL/DASP handshake.

catgen_dbmap
Map the user's given parameters to new credentials. This function is used when performing role mapping.

catgen_err
Generate error messages. This is a wrapper function for caterr_error().

catgen_fixservice
Splits an Agent service-version string.

catgen_getint
Retrieve an integer from the info tree.

catgen_getopt
Retrieve the command line arguments.

catgen_infopath
Set the search path to be used when searching for parameters in the info tree.

catgen_init
Initialize the Agent SDK and create and initialize the info tree. This function should called after catgen_parseargs().

catgen_initboks
Initialize the Keon 4.x (BoKS) interface.

catgen_initdebug
Initialize debug tracing by setting the debug specification retrieved from a command line option or from the info tree.

catgen_initels
Initialize the Event Logging System (ELS) interface by reading the info tree. If no ELS servers have been configured, ELS will not work.

catgen_initlog
This function initializes the catgen log labels for a service. The label definitions are process-global.

catgen_initlogfile
Set up logging to a local file rather than to Keon 4.5 (BoKS) or the ELS.

catgen_listen
Install listener sessions in the framework and set up other CAT information necessary for the session.

catgen_loadloglabels
This function registers catgen log messages in the logging system with an arbitrary facility and facility code.

catgen_log
Log a predefined log message.

catgen_newnode
Create a new node in the info tree.

catgen_parseargs
Parse arguments from the command line. The function automatically recognizes standard Agent parameters.

catgen_protocol
Determine the protocol that has been specified (DASP/SSL/PLAIN).

catgen_run
Run the sessions and automatically poll any relevant file descriptors for data. When this function returns, the program should finish.

catgen_server
Run a complete Agent. Using this function, only the protocol-specific parts need to be implemented.

catgen_serverencryption
Handle server side encryption and authentication handshaking.

catgen_servicepath
Get the full path for a service component in the info tree.

catgen_set
Insert information in the session-specific parts of the info tree.

catgen_warn
This function is a wrapper to caterr_error(), used to generate warnings. A warning is an error message of type CAT_WARNING.

SEE ALSO

cat, catinfo

catgen_certerrtologid, catgen_checkauth, catgen_dbmap, catgen_err, catgen_fixservice, catgen_getint, catgen_getopt, catgen_infopath, catgen_init, catgen_initboks, catgen_initdebug, catgen_initels, catgen_initinfo, catgen_initlog, catgen_initlogfile, catgen_listen, catgen_loadloglabels, catgen_log, catgen_newnode, catgen_parentcmd, catgen_parseargs, catgen_protocol, catgen_run, catgen_server, catgen_serverencryption, catgen_servicepath, catgen_set, catgen_warn

cfgfiles, gencfg