KeyStore Class Reference

Key store for external (MBK encrypted) keys. More...

Public Types
enum	modes {   MODE_EQUAL = 0 , MODE_GTEQ , MODE_GREATER , MODE_EQUAL = 0 ,   MODE_GTEQ , MODE_GREATER }
enum	modes {   MODE_EQUAL = 0 , MODE_GTEQ , MODE_GREATER , MODE_EQUAL = 0 ,   MODE_GTEQ , MODE_GREATER }

Public Member Functions
	KeyStore (const char *filename, int idx_len)
	KeyStore (Config &config, int idx_len)
virtual	~KeyStore (void)
int	getIndexLength () const
bool	findKey (ByteArray &startIndex, int mode, PropertyList *keyTemplate=NULL)
Key	getKey (ByteArray &index)
void	insertKey (int flags, ByteArray *index, const Key *key)
void	deleteKey (const ByteArray &index)

Detailed Description

Key store for external (MBK encrypted) keys.

On creation or import of a key on the CryptoServer, it can either be stored on the CryptoServer or exported as an external key (flag CXI_KEY_FLAG_EXTERNAL). In the latter case the key is encrypted with the CryptoServer's Master Backup Key (MBK). Such external keys can be stored in an external key database provided by this class.
Each record in a key store database consists of two fields:

• A search key (index) that uniquely identifies the record within the database.
• A data field where the key blob is stored.

The index fields of all records have the same length. This length has to be defined on creation of the database and can't be changed later.
Most commonly the unique key name (MD5 hash over name, group and specifier) with a length of 16 bytes is used as index (see Key::getUName()).
But the application may use any other index (e.g. a continuous serial number) to identify a key.

The length of the data field is variable.

Note

The database driver allows parallel access form multiple processes / threads on the local computer.
If the database file resides on a network share it may not be accessed from different computers.

Example:

The following example illustrates the usage of the KeyStore class:

// create an external key
Key key = cxi->key_generate(CXI_KEY_FLAG_EXTERNAL, keyTemplate);
 
// open / create key store (index length is 16 bytes)
KeyStore ks = KeyStore("d:/temp/cxi.ks", 16);
 
// insert key with its original index (unique name)
ByteArray index = key.getUName();
ks.insertKey(CXI_KEY_FLAG_OVERWRITE, index, key);
 
// insert key again but use the first free index
index = ByteArray();
ks.insertKey(CXI_KEY_FLAG_OVERWRITE, index, key);
 
// insert key again but use a specified index
index = ByteArray("\0\0\0\0\0\0\0\0\0\0\0\0\0\6\6\6", 16);
ks.insertKey(CXI_KEY_FLAG_OVERWRITE, index, key);
 
// get key
key = ks.getKey(index);
 
if (key.getType() == Key::TYPE_BLOB)
 PropertyList propList = key.getProplist();
 
// list all keys with a given name
PropertyList keytemplate;
keytemplate.setName("MyKeyName");
 
ByteArray searchIndex;
int mode = KeyStore::MODE_GTEQ;
 
while (ks.findKey(searchIndex, mode, keyTemplate) == true)
{
  searchIndex.xtrace("searchIndex");
  mode = KeyStore::MODE_GREATER;
}

Member Enumeration Documentation

modes [1/2]

enum modes

Modes for KeyStore::findKey

Enumerator
MODE_EQUAL	search key with exactly the given index
MODE_GTEQ	search key with the given or next greater index
MODE_GREATER	search key with the next greater index
MODE_EQUAL	search key with exactly the given index
MODE_GTEQ	search key with the given or next greater index
MODE_GREATER	search key with the next greater index

modes [2/2]

enum modes

Modes for KeyStore::findKey

Enumerator
MODE_EQUAL	search key with exactly the given index
MODE_GTEQ	search key with the given or next greater index
MODE_GREATER	search key with the next greater index
MODE_EQUAL	search key with exactly the given index
MODE_GTEQ	search key with the given or next greater index
MODE_GREATER	search key with the next greater index

Constructor & Destructor Documentation

KeyStore() [1/2]

KeyStore	(	const char *	filename,
		int	idx_len
	)

Opens a local key store database or creates it if not existing.

Parameters

filename	filename (including path) of keystore database
idx_len	size of database index. If the database should be created a non-zero value has to be given. The maximum size of the database index is 100. If a value of zero is given an existing database is opened and the length of the index is read from the database.

Note:

• the database index size is set on database creation and can't be changed later.

Exceptions

cxi::Exception

if database can't be opened

KeyStore() [2/2]

KeyStore	(	Config &	config,
		int	idx_len
	)

Opens a local key store database or creates it if not existing.

Parameters

config	Configuration object. The following key names will be recognized: Key Mandatory Default Value Description KeyStore Yes - filename (including path) of key store database. Use forward slashes as path separator (even on Windows).
idx_len	size of database index. If the database should be created a non-zero value has to be given. The maximum size of the database index is 100. If a value of zero is given an existing database is opened and the length of the index is read from the database.

Note:

• the database index size is set on database creation and can't be changed later.

Exceptions

cxi::Exception

if configuration doesn't contain a KeyStore entry or if database can't be opened

~KeyStore()

~KeyStore ( void  )

virtual

Closes key store database

Member Function Documentation

getIndexLength()

int getIndexLength

(

)

const

Returns the length of the database index.

findKey()

bool findKey	(	ByteArray &	startIndex,
		int	mode,
		PropertyList *	keyTemplate = NULL
	)

Finds a key with the given properties. Call the function multiple times to list all keys (with the desired properties).

Parameters

startIndex	Index to start search.
mode	Search mode: MODE_EQUAL - search key with exactly the given index MODE_GTEQ - search key with exactly the given index or the next greater index MODE_GREATER - search key with the next greater index
keyTemplate	Optional list of properties the desired key should match.

Returns

true if database entry was found, otherwise false.

Exceptions

cxi::Exception

getKey()

Key getKey

(

ByteArray &

index

)

Returns the key with the given index.

Parameters

index

Index of key to be retrieved.

Returns

Desired key

Exceptions

cxi::Exception

if key does not exist.

insertKey()

void insertKey	(	int	flags,
		ByteArray *	index,
		const Key *	key
	)

Inserts a key into the key store. The key will be stored under the given index.

Parameters

flags	CXI_KEY_FLAG_OVERWRITE, if an existing key should be overwritten.
index	Database index for the key to be inserted. If an empty ByteArray is given, the first free index will be used and the index value will be updated with the actual value.
key	Key to be inserted.

Exceptions

cxi::Exception

deleteKey()

void deleteKey

(

const ByteArray &

index

)

Deletes the key with the given index.

Parameters

index

Index of key to be deleted.

Exceptions

cxi::Exception

if key does not exist