cat - CAT (Keon Agent SDK 5.1)
The Keon Agent SDK 5.1 (CAT) is an API designed to allow the easy
development of RSA Keon Agents that handle strong authentication, encrypted
communication, and Secure Single Sign-On (SSSO) for application severs.
This API is intended for use in a Keon 4.5 (BoKS) or Keon 5.0 environment.
The API is divided into separate groups of functions. The base is the multi
level filter stack, where data can be inserted and extracted using a read
and a write function. Each filter pushed onto the filter stack is invoked
in sequence until the bottom of the stack is reached. An I/O Handler must
be installed at the bottom of the stack. The I/O Handler is called by the
filter stack framework whenever the filter at the bottom of the stack needs
to send out its data or whenever it (the filter) requires more input data.
The I/O Handler is responsible for carrying out I/O operations, and
sending/receiving data to/from the client and the server.
Up to two 2-way connections and any data associated with them are collected
into a ``session''. Since a session usually represents a connection between
a server and a client, one 2-way connection is referred to as the client
side, while the other is referred to as the server side. For each
connection, there are two data streams, referred to as ``file
descriptors.'' Normally, these have nothing to do with disk files, but are
any data stream produced by the I/O Handler, processed by the filter stack,
and consumed by the I/O Handler.
The read operation, cat_recv(),
operates on two file
descriptors
CAT_CLIENT_RFD
and CAT_SERVER_RFD
. The corresponding write operation, cat_send(),
operates on
the CAT_CLIENT_WFD
and CAT_SERVER_WFD
descriptors. It is up to the I/O Handler to map all these descriptors to
physical I/O channels or to generate a callback back to the Agent. For the
TCP/IP implementation of the I/O Handler,
CAT_CLIENT_RFD
and CAT_CLIENT_WFD
both map to a socket connected to the client. CAT_SERVER_RFD
and CAT_SERVER_WFD
both map to a socket connected to the server application.
CAT provides a set of functions used to filter TCP/IP traffic. Also
included is an I/O Handler implementation that must be installed by calling
cat_installiohandler().
Other functions included are used to
listen to client connections and to forward those connections to the server
application. Agents using these latter functions will act as a proxy. Since
the Agent will take over the task of listening for client connections from
the server application, some manual reconfiguration of the server
application may be necessary.
A set of generic high level API functions is provided. These functions hide
the data transport layer. Agents using these API functions will see only
the true data. This is the preferred way of writing Agents. Separate
configuration data (file or registry) will contain the details of the port
to listen to and how to connect to the server application.
Some platforms support the in-line filtering of TCP/IP traffic that is sent
to and received from a server application. This filtering eliminates the
need for the Agent to act as a proxy. Windows NT, for example, provides
support in the Winsock2 layer for the modification of TCP/IP data sent to
or received from an application. In some UNIX systems, write streams
modules can be written that filter the data in-line. Functions for handling
this can be added to the API in future versions, which will be compatible
with the high level API functions.
The API is divided into two different shared libraries (these are shared
libraries on UNIX and Dynamic link libraries on Windows NT) with
corresponding header files.
The libraries are
- cat
-
The base library, containing all low-level functions. In general, Agent
developers should need to access directly only a small part of this
library.
- catgen
-
This is a layer above the base library that is intended to provide a higher
level of abstraction and thus the simpler development of Agents. The
functions in this library should be used when developing Agents.
This library uses the base library.
Unless stated otherwise, all functions contained in the API will work on
all platforms. These platforms currently comprise Solaris, HP-UX, AIX, and
Windows NT 4.0).
The API is currently divided into several groups of interfaces. Each group
has it's own head page which points to the different functions in that
group. The following is a brief overview of these groups.
- Basic filter stack handler
-
Provides a method for filtering data in multiple levels. Filters are pushed
onto a filter stack, and all data read or written is passed through each
filter. For an overview of the available functions, refer to the Function Overview section.
- Buffer management
-
Data is passed up and down the filter stacks in dynamic buffers. See the catbuf page for an overview of the buffer management functions.
- Error handling
-
These functions define callback routines that are called whenever errors
occur. This provides for centralized error management.
caterr describes the error handling functions.
- TCP/IP network I/O-Handler
-
Provides a standard environment for implementing TCP/IP proxy filters. The
typedef CATSOCK maps to the file descriptor used for socket programming in
the different environments. ``
typedef int
CATSOCK
'' on Unix and ``typedef SOCKET CATSOCK
'' on NT. The catnet page describes the available network functions.
- SSL protocol
-
Provides functions for negotiating SSL on both the server and client sides.
SSL data layer filters are provided that handle data packet wrapping after
the SSL negotiation has succeeded. Also read the catssl page.
- DASP protocol
-
Provide functions to negotiate the DASP protocols ALLTAK and ALLTAAS both
as a server and a client, and to perform data stream encryption after a
successful negotiation. A closer description is available in the
catdasp page.
- PAC & EAR interface
-
Functions to authenticate and extract data from the PAC. Also read the catpac page.
- PSD interface
-
Routines for opening a PSD (Virtual Card) by PIN code; extracting the
certificate, and encryption with the private key. Also read the catpsd page.
- Keon Security Server 4.5 (BoKS) interface
-
Provides functions to ask BoKS questions regarding for example, route
status and authorization. More information about available functions can be
found in the catboks page.
- Event Logging
-
Functions used for authentication and debug logging. Also read the catlog page.
- Configuration information interface
-
Provides functions to read and set configuration parameters. Also read the catinfo page.
- Certificate functions
-
Miscellaneous functions used to extract values from certificates. More
information can be found in the catcert page.
- High level generic functions
-
Functions that provide platform and transport layer independence. They
automatically determine the connection type, the authentication type, the
encryption type, etc. Also read the catgen page.
- Configuration parameters
-
Provide a quick layout of the configuration parameters. The true definition
is in the administration specification.
- Utility functions
-
Miscellaneous functions used in different parts of the toolkit. Se also the catutil page.
- cat_close
-
Close a cat session by popping all filters, and free any resources.
- cat_getsessdata
-
Get session-specific data that has been registered with cat_setsessdata().
- cat_getsessid
-
Return the process-unique identifier for the session.
- cat_init
-
Initialize the Agent SDK libraries.
- cat_installiohandler
-
Register the I/O handling functions. The only I/O handler available in the
Agent SDK is for TCP/IP. However, you can write your own I/O handler and
install it using this function.
- cat_newdatakey
-
Create a memory slot, which can be used to store session-specific data, in
each session.
- cat_newssion
-
Create a new b<cat> session framework, including an empty filter
stack.
- cat_onclose
-
Register a callback to be called by the framework when the session is
closed.
- cat_peekfilter
-
Return information about a specified filter.
- cat_poll
-
Wait for data at the specified file descriptors.
- cat_popfilter
-
Pop (remove) the topmost filter in the filter stack.
- cat_pushfilter
-
Push a filter onto the filter stack.
- cat_recv
-
Read data from a file descriptor, filtering the data through any pushed
filters.
- cat_runsingle
-
Set a single session into server mode.
- cat_send
-
Send data through the filter stack.
- cat_setsessdata
-
Register data for a specific session using key form cat_newdatakey(). The data can be retrieved with a call to cat_getsessdata().
All functions are MT safe unless stated otherwise in the documentation for
the specific functions.
The CAT provides a set of generic error codes. Functions can return one of these or
a value as specified in the documentation for the specific function. Code 0
is synonymous with CAT_OK. All other error codes are negative and defined in caterr.
catbuf, catboks, catcert, catdasp,caterr, catgen,
catinfo, catlog, catnet, catpac, catpsd, catssl,
catutil
cat_close, cat_getsessdata, cat_getsessid,
cat_init, cat_installiohandler, cat_newdatakey,
cat_newsession, cat_onclose, cat_poll, cat_peekfilter
cat_popfilter, cat_pushfilter, cat_recv, cat_runsingle,
cat_send, cat_setsessdata
catd, catlogger, config, iwrap, pp, ppmk, start
ADF, cfgfiles, description
In general, all functions in the API must be preceded by a call to
cat_init(). If a function can be called before cat_init(), this is noted in the documentation.