com.rsa.certj.provider.db

Class NativeDB

java.lang.Object
  |
  +--com.rsa.certj.Provider
        |
        +--com.rsa.certj.provider.db.NativeDB

public final class NativeDB

extends Provider

This class implements a database provider that stores data in a persistent local database. Database entries are stored as records in files in the local file system. The database engine is an embedded, high-performance engine that is suitable for managing small to medium numbers of entries.

Database Names

Databases are identified by a 1 to 32 character name that is assigned when the database is created. It is one of the parameters of each constructor in the class.

An individual database consists of several files, all stored in the same directory. It is not necessary to create each database in a different directory. Multiple databases and all their associated files can reside in the same directory, because the database service provider keeps track of the files that belong with a particular database name.

Database Structure and File Names

Each database consists of three components: one stores certificates, a second one stores CRLs, and a third one stores private keys. Each component consists of three local files, each of which has a different file type extension: cdx, dbf, or fpt. Each database consists of nine local files.

In addition, the NativeDB provider creates master table files in each directory that contains databases. The master table files keep information about all the databases stored in the directory. The master table files are called rsadb.cdx and rsadb.dbf.

The NativeDB provider does not use the database name passed to the class to form the names of the the database files. Instead it maps each database name to a particular ID, and uses the ID to determine the name of each database file. The mapping information and the database file names are stored in the master table files.

Example

If you provide MyDatabase as the name of a database to be created, and it is mapped to the ID aaaaaaa, nine files are created.

Three files for certificate storage:

• caaaaaaa.cdx
• caaaaaaa.dbf
• caaaaaaa.fpt

Three files for CRL storage:

• raaaaaaa.cdx
• raaaaaaa.dbf
• raaaaaaa.fpt

Three files for private key storage:

• paaaaaaa.cdx
• paaaaaaa.dbf
• paaaaaaa.fpt

Private-Key Storage Considerations

The confidentiality of private keys stored in the database is protected, using standard PKCS #5 Password-Based Encryption (PBE). When constructing a NativeDB object, supply a password to be used for private-key operations during that session. Each time a private key is inserted into the database, it is encrypted using the password. When a private key is retrieved from the database, the database provider attempts to decrypt the record using the supplied password. If the decryption succeeds, the private key is returned.

It is possible to store private keys encrypted with differing passwords in the same database. To change the password, first unregister the service provider and then re-register it with a different password.

Private-key database operations involves encryption operations that use random numbers. If you do not register a random service provider, the default random service provider is used.

Copyright © RSA Security Inc., 1999-2001. All rights reserved.

Constructor Summary

NativeDB(String name, File path, String databaseName, char[] password, boolean newDatabase)

Constructs a NativeDB object.

NativeDB(String name, String pathString, String databaseName, char[] password, boolean newDatabase)

Constructs a NativeDB object.

Method Summary

static boolean	create(File path, String databaseName) Creates NativeDB database storage for the database, databaseName, in the directory, path, when the path parameter is a File.
static boolean	create(String pathString, String databaseName) Creates NativeDB database storage for the database, databaseName, in the directory path when the path parameter is a String.
static boolean	delete(File path, String databaseName) Deletes NativeDB database storage for the database, databaseName, that is located at path, when the path parameter is a File.
static boolean	delete(String pathString, String databaseName) Deletes NativeDB database storage for the database, databaseName, that is located at path, when the path parameter is a String.
ProviderImplementation	instantiate(CertJ certJ) Creates a ProviderImplementation object that handles the database SPI methods for the NativeDB provider.
static String[]	listAllDatabaseNames(File path) Returns a list of all of the NativeDB database names in the directory, path, when the directory name is a File.
static String[]	listAllDatabaseNames(String pathString) Returns a list of all of the NativeDB database names in the directory, pathString, when the directory name is a String.

Methods inherited from class com.rsa.certj.Provider

getName, getType

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NativeDB

public NativeDB(String name,
                String pathString,
                String databaseName,
                char[] password,
                boolean newDatabase)
         throws InvalidParameterException,
                DatabaseException

Constructs a NativeDB object. The location of the database is given as a String. If the database is new, set the boolean argument newDatabase to true.

Parameters

	name		A String that indicates the name of the provider.
	pathString		A String that indicates a directory, on the local file system, where the database resides.
	databaseName		A String that indicates the name of the database.
	password		A char array that contains a password to be used to encrypt private keys.
	newDatabase		A boolean that indicates if a new database should be created.

Throws

InvalidParameterException - If any argument is invalid.

DatabaseException - If there is some unrecoverable error in the database.

NativeDB

public NativeDB(String name,
                File path,
                String databaseName,
                char[] password,
                boolean newDatabase)
         throws InvalidParameterException,
                DatabaseException

Constructs a NativeDB object. The location of the database is given as a File. If the database is new, set the boolean argument newDatabase to true.

Parameters

	name		A String that indicates the name of the provider.
	path		A File that indicates a directory, on the local file system, where the database resides.
	databaseName		A String that is the name of the database.
	password		A char array that contains a password to encrypt private keys.
	newDatabase		A boolean that indicates if a new database should be created.

Throws

InvalidParameterException - If any argument is invalid.

DatabaseException - If there is some unrecoverable error in the database.

Method Detail

create

public static boolean create(String pathString,
                             String databaseName)
                      throws InvalidParameterException,
                             DatabaseException

Creates NativeDB database storage for the database, databaseName, in the directory path when the path parameter is a String.

Parameters

	pathString		A String that indicates a directory, on the local file system, where the database resides.
	databaseName		A String that is the name of the database.

Returns

A boolean value that indicates whether the database was created successfully.

Throws

InvalidParameterException - If pathString and/or databaseName is null.

DatabaseException - If there is some unrecoverable error in the database.

create

public static boolean create(File path,
                             String databaseName)
                      throws InvalidParameterException,
                             DatabaseException

Creates NativeDB database storage for the database, databaseName, in the directory, path, when the path parameter is a File.

Parameters

	path		A File that indicates a directory, on the local file system, where the database resides.
	databaseName		A String that is the name of the database.

Returns

A boolean that indicates whether the database was created successfully.

Throws

InvalidParameterException - If path and/or databaseName is null.

DatabaseException - If there is some unrecoverable error in the database.

delete

public static boolean delete(String pathString,
                             String databaseName)
                      throws InvalidParameterException,
                             DatabaseException

Deletes NativeDB database storage for the database, databaseName, that is located at path, when the path parameter is a String.

Parameters

	pathString		A String that indicates a directory, on the local file system, where the database resides.
	databaseName		A String that is the name of the database.

Returns

A boolean value that indicates whether the deletion of the database is successful.

Throws

InvalidParameterException - If pathString and/or databaseName is null.

DatabaseException - If there is some unrecoverable error in the database.

delete

public static boolean delete(File path,
                             String databaseName)
                      throws InvalidParameterException,
                             DatabaseException

Deletes NativeDB database storage for the database, databaseName, that is located at path, when the path parameter is a File.

Parameters

	path		A File that indicates a directory, on the local filesystem, where the database resides.
	databaseName		A String that is the name of the database.

Returns

A boolean value that indicates whether the deletion of the database is successful.

Throws

InvalidParameterException - If path and/or databaseName is null.

DatabaseException - If there is some unrecoverable error in the database.

listAllDatabaseNames

public static String[] listAllDatabaseNames(String pathString)
                                     throws InvalidParameterException,
                                            DatabaseException

Returns a list of all of the NativeDB database names in the directory, pathString, when the directory name is a String.

Parameters

pathString

A String that specifies the directory to be searched for database names.

Returns

A String array that contains all the database names found, or null if none is found.

Throws

InvalidParameterException - If pathString is null.

DatabaseException - If there is some unrecoverable error in the database.

listAllDatabaseNames

public static String[] listAllDatabaseNames(File path)
                                     throws InvalidParameterException,
                                            DatabaseException

Returns a list of all of the NativeDB database names in the directory, path, when the directory name is a File.

Parameters

path

A File that specifies the directory to be searched for database names.

Returns

A String array that contains all the database names found, or null if none is found.

Throws

InvalidParameterException - If path is null.

DatabaseException - If there is some unrecoverable error in the database.

instantiate

public ProviderImplementation instantiate(CertJ certJ)
                                   throws ProviderManagementException

Creates a ProviderImplementation object that handles the database SPI methods for the NativeDB provider. It throws an exception if the newDatabase argument is set to true, and there already exists a database named databaseName at the location path. This method is called by CertJ.registerService when an object of the NativeDB class is being registered; applications do not have to call this method.

Overrides

instantiate in class Provider

Parameters

certJ

A CertJ for which the created provider is registered.

Returns

A ProviderImplementation object that handles the NativeDB Database SPI methods.

Throws

ProviderManagementException - If instantiation of the NativeDB provider fails.