NAME

cat - CAT (Keon Agent SDK 5.1)

DESCRIPTION

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.

Design

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.

Structure

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.

Portability

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).

Interface overview

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.

Function Overview

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().

MT Safeness

All functions are MT safe unless stated otherwise in the documentation for the specific functions.

RETURN VALUES

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.

SEE ALSO

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

NOTES

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.