Download user manual

The Database Backend Interface
317
Database and Networking Plugins
In order to communicate with databases that are used as certificate stores and with
different network types, cryptlib uses a plugin interface that allows it to talk to any
type of database back-end and network protocol. The database interface provides
four functions that are used to interface to the back-end, two functions to open and
close the connection to the back-end and two to send data to and read data from it.
The network plugin interface provides five functions, two to initialise and shut down
the connection, two to read and write data, and one to check that the networking
interface provided by the interface has been correctly initialised. The network plugin
allows cryptlib to use any kind of network interface, either a customised form of the
built-in BSD sockets interface or a completely different network mechanism such as
SNA or X.25.
The Database Backend Interface
The database backend interface is used when cryptlib receives a user request to access
a database of type CRYPT_KEYSET_DATABASE or CRYPT_KEYSET_DATABASE_STORE (and by extension for the various CRYPT_KEYSET_ODBC
and CRYPT_KEYSET_ODBC_STORE types as well, although these are
preconfigured and don’t require any further setup). The first thing that cryptlib does
is call the initDbxSession() function in keyset/dbms.c, which connects the
generic database type to the actual database backend-specific code (for example an
Oracle, Sybase, or PostgreSQL interface).
The structure of the database interface is as follows:
#include "keyset/keyset.h"
/* Plugin functions: openDatabase(), closeDatabase(), performUpdate(),
performQuery() */
int initDispatchDatabase( DBMS_INFO *dbmsInfo )
{
dbmsInfo->openDatabaseBackend = openDatabase;
dbmsInfo->closeDatabaseBackend = closeDatabase;
dbmsInfo->performUpdateBackend = performUpdate;
dbmsInfo->performQueryBackend = performQuery;
return( CRYPT_OK );
}
keyset/keyset.h contains the keyset-related defines that are used in the code, and the
dispatcher initialisation function sets up function pointers to the database access
routines, which are explained in more detail below. State information about a session
with the database is contained in the DBMS_STATE_INFO structure which is
defined in keyset/keyset.h. This contains both shared information such as the last
error code and the status of the session, and back-end -specific information such as
connection handles and temporary data areas. When you create ain interface for a
new database type, you should add any variables that you need to the databasespecific section of the DBMS_STATE_INFO structure. When cryptlib calls your
interface functions it will pass in the DBMS_STATE_INFO that you can use to store
state information.
Database Interface Functions
The database interface functions that you need to provide are as follows:
static int openDatabase( DBMS_STATE_INFO *dbmsInfo, const char *name,
const int nameLen, const CRYPT_KEYOPT_TYPE options,
int *featureFlags )
This function is called to open a session with the database. The parameters are the
name of the database to open the session to and a set of option flags that apply to the
session. The name parameter is a composite value that depends on the underlying
database being used, usually this is simply the database name, but it can also contain
a complete user name and password in the format user:pass@server. Other