RSA BSAFE Cert-C API Reference

Cert-C Default Database Service Provider

The Cert-C Default Database service provider provides a persistent local database. Database entries are stored as records in files in the local file system. The database is implemented using an embedded, high-performance database engine suitable for managing small to medium numbers of entries, for example, up to tens of thousands of entries.

Databases are identified by a name composed from 1 to 32 characters. This name is assigned when the database is created, and it must be included as one of the parameters of the Cert-C Default Database service provider when the application registers the database.

An individual database consists of several files, all stored in the same directory. The Cert-C Default Database service provider keeps track of the files that belong with a particular database name so the application can create several databases with different names in the same directory.

The confidentiality of private-keys stored in the database is protected using standard PKCS #5 v2.0 PBE. The password-based key derivation function is PBKDF2, and the password-based encryption scheme is PBES2. The encryption scheme is DES-EDE3-CBC-Pad. When registering a database, 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 attempts to decrypt the record using the supplied password. If the decrypting succeeds, the private key is returned.

Private keys encrypted with different passwords can be stored in the same database. To change the password being used, unregister the service provider and re-register it with a different password.

Because private-key database operations use cryptography, be sure to register a cryptographic service provider. If no cryptographic service provider is registered, private-key database operations return an error.

To initialize or register the Cert-C Default Database service provider, call either the C_InitializeCertC or the C_RegisterService function. Both functions take SERVICE_HANDLER as a parameter. The Initialize member in SERVICE_HANDLER points to the S_InitializeDefaultDB function. The corresponding POINTER should point to a DEFAULT_DB_PARAMS structure, or it should be NULL_PTR. The S_InitializeDefaultDB function initializes the Cert-C Default Database service provider's implementation of the database functions and stores pointers to them in SERVICE_FUNCS's db member, which is a DB_FUNCS structure. Never call S_InitializeDefaultDB directly.

To use the Cert-C Default Database service provider in an application, link in the certcsp library and include the rsadb.h header file. The rsadbcert sample uses this service provider.

Cert-C Database Command-Line Utility

Cert-C includes a database command-line utility program, which can create, list, and delete databases for use with the Cert-C Default Database service provider. For a detailed description of this utility, see the "Database Command-Line Sample" in the "Cert-C Detailed Samples" chapter of the Advanced Developer's Guide.