gsk_open_database_using_stash

Opens a key or request database using a stash file for the database password.

Format

#include <gskcms.h>

gsk_status gsk_open_database_using_stash_file (
                                               const char *            database_filename,
                                               const char *            stash_filename,
                                               gsk_boolean             update_mode,
                                               gsk_handle *            db_handle,
                                               gskdb_database_type *   db_type,  
                                               int *                   num_records)

Parameters

database_filename: Specifies the database file name in the local code page. The length of the fully-qualified filename cannot exceed 251.
stash_filename: Specifies the stash file name in the local code page. The length of the fully-qualified filename cannot exceed 251. The stash file name always has an extension of ".sth" and the supplied name will be changed if it does not have the correct extension.
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_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_NOT_FIPS]: Key database is not a FIPS mode database.
[CMSERR_FILE_NOT_FOUND]: The database file is not found.
[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_using_stash_file() routine is the same as the gsk_open_database() routine except the database password is obtained from the password stash file instead of being specified as a call parameter. The key or request database can be opened for read-only access or for 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.