gsk_open_database()

Opens a key or request database.

Format

#include <gskcms.h>

gsk_status gsk_open_database (
                              const char *                filename,
                              const char *                password,
                              gsk_boolean                 update_mode,
                              gsk_handle *                db_handle,
                              gskdb_database_type *       db_type,  
                              int *                       num_records)

Parameters

filename: Specifies the database file name in the local code page. The length of the fully-qualified filename cannot exceed 251.
password: Specifies the database password in the local code page. The user will be prompted to enter the password if NULL is specified for this parameter.
update_mode: Specifies the file access mode. Specify TRUE if the database will be updated and FALSE if the database will not be updated. The application must have write access to the file if TRUE is specified.
db_handle: Returns the database handle. The application should call the gsk_close_database() routine when it no longer needs access to the database.
db_type: Returns the database type.
num_records: Returns the number of records in the database.

Results

The function return value will be 0 if no error is detected. Otherwise, it will be one of the return codes listed in the gskcms.h include file. These are some possible errors:

[CMSERR_ACCESS_DENIED]: The file permissions do not allow access.
[CMSERR_BAD_FILENAME]: The database file name is not valid.
[CMSERR_BAD_RNG_OUTPUT]: In FIPS mode, random bytes generation produced duplicate output.
[CMSERR_DB_CORRUPTED]: The database file is not valid.
[CMSERR_DB_FIPS_MODE_ONLY]: Key database can only be opened for update if running in FIPS mode.
[CMSERR_DB_LOCKED]: The database is open for update by another process.
[CMSERR_DB_NOT_FIPS]: Key database is not a FIPS mode database.
[CMSERR_FILE_NOT_FOUND]: The database file is not found.
[CMSERR_IO_CANCELED]: The user canceled the password prompt.
[CMSERR_IO_ERROR]: An input/output request failed.
[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_OPEN_FAILED]: Unable to open the database.

Usage

The gsk_open_database() routine will open a key or request database file for either read-only or read/write access. The database must already exist. The database integrity will be verified and the open will fail if the database has been incorrectly modified. Only one process at a time may open a database in update mode. The database may be accessed by multiple concurrent threads in the same process if the same database handle is used by all of the threads.

A FIPS database file may only be opened for update while executing in FIPS mode. A FIPS database may be opened read-only while executing in non-FIPS mode. A non-FIPS database file cannot be opened for read or update while executing in FIPS mode.