com.rsa.certj.provider.db

Class FlatFileDB

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

public final class FlatFileDB

extends Provider

This class implements a database service provider that stores data in a simple flat file database.

In the database directory are four subdirectories: certs, crls, privs and pubs, storing certificates, CRLs, private keys, and public keys respectively.

The length of file names and the length of name prefixes can be selected. The following description assumes that the length of file names is 8 characters, with the first 2 characters indicating the prefix. Prefixes are used to distinguish different entities that share the same hash value.

The FlatFileDB database provider stores data in the following manner:

Certificates

1. Hashes the issuer name BER encoding and the serial number.
2. Takes the bottom 3 bytes and converts to hexidecimal.
3. Prepends a prefix in the first byte, starting with 00. For example, if the hash is 0x123456789abcdef, the file names would be 00abcdef.cer, 01abcdef.cer, 02abcdef.cer, etc. The third certificate that has abcdef in the bottom 3 bytes of the hash value is stored in certs/02abcdef.cer.

CRLs

1. Hashes the issuer name BER encoding.
2. Takes the bottom 3 bytes and converts to hexidecimal.
3. Prepends a prefix in the first byte, starting with 00. For example, if the hash is 0x123456789abcdef, the file names would be 00abcdef.crl, 01abcdef.crl, 02abcdef.crl, etc. The third certificate that has abcdef in the bottom 3 bytes of the hash value is stored in crls/02abcdef.crl.

Private Keys

Private keys are stored together with corresponding public keys to identify the private keys. A pair consisting of a private key and the corresponding public key shares the same file name, but the extensions are different. For example, if a public key is stored in pubs/00abcdef.pub, the corresponing private key is stored in privs/00abcdef.prv. The file name for a key pair is determined as follows:

1. Gets modulus of the public key.
2. The same as step 2 of "Certificates" above.
3. The same as step 3 of "Certificates" above except that public keys are stored in the pubs directory using the file type pub and private keys are stored in the privs directory using the file type prv.

Private Key Storage Considerations

The confidentiality of private keys stored in the database is protected using standard PKCS #12 Password Based Encryption (PBE). When you construct a FlatFileDB object, you 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.

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

Field Summary

static int	DEFAULT_BASE_NAME_LEN An int indicating the default base name length for database file names.
static int	DEFAULT_PREFIX_LEN An int indicating the default prefix length for database file names.

Constructor Summary

FlatFileDB(String name, File path, char[] passphrase)

Constructs a FlatFileDB object.

FlatFileDB(String name, File path, char[] passphrase, int baseNameLen, int prefixLen)

Constructs a FlatFileDB object.

FlatFileDB(String name, String pathString, char[] passphrase)

Constructs a FlatFileDB object.

FlatFileDB(String name, String pathString, char[] passphrase, int baseNameLen, int prefixLen)

Constructs a FlatFileDB object.

Method Summary

static boolean	create(File path) Creates FlatFileDB database directories, in a location specified by path when path is a File.
static boolean	create(String pathString) Creates FlatFileDB database directories, in a location specified by path when path is a String.
static boolean	delete(File path) Deletes FlatFileDB database files located at path given as a File.
static boolean	delete(String pathString) Deletes FlatFileDB database files located at path given as a String.
ProviderImplementation	instantiate(CertJ certJ) Creates a ProviderImplementation object that handles flat-file database SPI methods.

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

Field Detail

DEFAULT_BASE_NAME_LEN

public static final int DEFAULT_BASE_NAME_LEN

An int indicating the default base name length for database file names. This value is used when you construct a FlatFileDB object by using a constructor that does not take a base name length as an argument.

DEFAULT_PREFIX_LEN

public static final int DEFAULT_PREFIX_LEN

An int indicating the default prefix length for database file names. This value is used when you construct a FlatFileDB object by using a constructor that does not take a prefix length as an argument.

Constructor Detail

FlatFileDB

public FlatFileDB(String name,
                  String pathString,
                  char[] passphrase)
           throws InvalidParameterException

Constructs a FlatFileDB object. The location of the database is given as a String. The default values (DEFAULT_BASE_NAME_LEN and DEFAULT_PREFIX_LEN) will be used for the length of the base name and the length of the prefix of file names.

Parameters

	name		A String that holds the name of this provider.
	pathString		A String that holds the directory to be used for this database.
	passphrase		A char array that holds the password to use for encrypting private keys.

Throws

InvalidParameterException - If any argument is invalid.

FlatFileDB

public FlatFileDB(String name,
                  File path,
                  char[] passphrase)
           throws InvalidParameterException

Constructs a FlatFileDB object. The location of the database is given as a File. The default values (DEFAULT_BASE_NAME_LEN and DEFAULT_PREFIX_LEN) will be used for the length of the base name and the length of the prefix of file names.

Parameters

	name		A String that holds the name of this provider.
	path		A File that holds the directory to use for this database.
	passphrase		A char array that holds the password to use for encrypting private keys.

Throws

InvalidParameterException - If any argument is invalid.

FlatFileDB

public FlatFileDB(String name,
                  String pathString,
                  char[] passphrase,
                  int baseNameLen,
                  int prefixLen)
           throws InvalidParameterException

Constructs a FlatFileDB object. The location of database is given as a String and the length of the base name and length of the prefix are given by the arguments.

Parameters

	name		A String that holds the name of this provider.
	pathString		A String that holds the directory to use for this database.
	passphrase		A char array that holds the password to use for encrypting private keys.
	baseNameLen		An int that indicates the number of characters used for the base name part of file names.
	prefixLen		An int that indicates the number of characters used for the prefix part of file names.

Throws

InvalidParameterException - If any argument is invalid.

FlatFileDB

public FlatFileDB(String name,
                  File path,
                  char[] passphrase,
                  int baseNameLen,
                  int prefixLen)
           throws InvalidParameterException

Constructs a FlatFileDB object. The location of database is given as a File and the length of the base name and length of the prefix are given by the arguments.

Parameters

	name		A String that holds the name of this provider.
	path		A File that holds the directory to use for this database.
	passphrase		A char array that holds the password to use for encrypting private keys.
	baseNameLen		An int that indicates the number of characters used for the base name part of file names.
	prefixLen		An int that indicates the number of characters used for the prefix part of file names.

Throws

InvalidParameterException - If any argument is invalid.

Method Detail

create

public static boolean create(String pathString)
                      throws InvalidParameterException

Creates FlatFileDB database directories, in a location specified by path when path is a String.

Parameters

pathString

A String that indicates a directory, on the local file system where the database resides.

Returns

A boolean that indicates whether the database was created successfully.

Throws

InvalidParameterException - If pathString is null.

create

public static boolean create(File path)
                      throws InvalidParameterException

Creates FlatFileDB database directories, in a location specified by path when path is a File.

Parameters

path

A File that indicates a directory, on the local file system, where the database resides.

Returns

A boolean that indicates whether the database was created successfully.

Throws

InvalidParameterException - If path is null.

delete

public static boolean delete(String pathString)
                      throws InvalidParameterException

Deletes FlatFileDB database files located at path given as a String.

Parameters

pathString

A String that indicates a directory, on the local file system, where the database resides.

Returns

A boolean that indicates whether the database was deleted successfully.

Throws

InvalidParameterException - If pathString is null.

delete

public static boolean delete(File path)
                      throws InvalidParameterException

Deletes FlatFileDB database files located at path given as a File.

Parameters

path

A File that indicates a directory, on the local file system, where the database resides.

Returns

A boolean that indicates whether the database was deleted successfully.

Throws

InvalidParameterException - If path is null.

instantiate

public ProviderImplementation instantiate(CertJ certJ)
                                   throws ProviderManagementException

Creates a ProviderImplementation object that handles flat-file database SPI methods. This method is called by CertJ.registerService when an object of the FlatFileDB class is being registered and applications do not have to call this method.

Overrides

instantiate in class Provider

Parameters

certJ

A CertJ object for which the created provider is registered.

Returns

A ProviderImplementation object that handles the flat file database SPI implementation.

Throws

ProviderManagementException - If instantiation of the flat file database provider fails.