catgen - generic high level functions
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.
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.
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_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.
- 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.
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