gsk_replace_record()

Replaces a record in a key or request database.

Format

#include <gskcms.h>

gsk_status gsk_replace_record (
                               gsk_handle                 db_handle,
                               gskdb_record *             record)

Parameters

db_handle: Specifies the database handle returned by the gsk_create_database() routine or the gsk_open_database() routine.
record: Specifies the database record.

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_ALG_NOT_SUPPORTED]: The signature algorithm is not supported.
[CMSERR_BACKUP_EXISTS]: The backup file already exists.
[CMSERR_BAD_HANDLE]: The database handle is not valid.
[CMSERR_BAD_KEY_SIZE]: The key size is not valid.
[CMSERR_BAD_LABEL]: The record label is not valid.
[CMSERR_BAD_RNG_OUTPUT]: In FIPS mode, random bytes generation produced duplicate output.
[CMSERR_DEFAULT_KEY_CHANGED]: The default key cannot be changed.
[CMSERR_ECURVE_NOT_FIPS_APPROVED]: Elliptic Curve not supported in FIPS mode.
[CMSERR_ECURVE_NOT_SUPPORTED]: Elliptic Curve is not supported.
[CMSERR_ICSF_FIPS_DISABLED]: ICSF PKCS #11 services are disabled.
[CMSERR_ICSF_NOT_AVAILABLE]: ICSF services are not available.
[CMSERR_ICSF_NOT_FIPS]: ICSF PKCS #11 not operating in FIPS mode.
[CMSERR_ICSF_SERVICE_FAILURE]: ICSF callable service returned an error.
[CMSERR_INCORRECT_DBTYPE]: The record type is not supported for the database type.
[CMSERR_IO_ERROR]: Unable to write record.
[CMSERR_LABEL_NOT_UNIQUE]: The record label is not unique.
[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_NO_PRIVATE_KEY]: No private key is provided for a record type that requires a private key.
[CMSERR_PUBLIC_KEY_CHANGED]: The subject public key cannot be changed.
[CMSERR_RECORD_NOT_FOUND]: Record is not found.
[CMSERR_RECORD_TOO_BIG]: The record is larger than the database record length.
[CMSERR_RECTYPE_NOT_VALID]: The record type is not valid.
[CMSERR_SUBJECT_CHANGED]: The subject name cannot be changed.
[CMSERR_UPDATE_NOT_ALLOWED]: Database is not open for update or update attempted on a FIPS mode database while in non-FIPS mode.

Usage

The gsk_replace_record() routine replaces a record in a key or request database. The database must be open for update in order to replace records. The unique record identifier identifies the record to be replaced. Unused and reserved fields in the gskdb_record structure must be initialized to zero. If the record has a private key, the encrypted private key will be generated from the private key supplied in the database record.

The recordType field identifies the database record type as follows:

gskdb_rectype_certificate: The record contains an X.509 certificate.
gskdb_rectype_certKey: The record contains an X.509 certificate and private key.
gskdb_rectype_keyPair: The record contains a PKCS #10 certification request and private key.

The recordFlags field is a bit field with these values:

GSKDB_RECFLAG_TRUSTED: The certificate is trusted.
GSKDB_RECFLAG_DEFAULT: This is the default key

The record label is used as a friendly name for the database entry and is in the local code page. It can be set to any value and consists of characters which can be represented using 7-bit ASCII (letters, numbers, and punctuation). It may not be set to an empty string.

If the record contains a certificate, the certificate will be validated and the record will not be replaced in the database if the validation check fails. If executing in FIPS mode, only FIPS-approved algorithms and key sizes are supported.

With the exception of the record label, all character strings are specified using UTF-8.

The record type, subject name, and subject public key cannot be changed when replacing a record. In addition, the GSKDB_RECFLAG_DEFAULT flag cannot be changed when replacing a record (call the gsk_set_default_key() routine to change the default record for the database).

The database file is updated as part of the gsk_replace_record() processing. A temporary database file is created using the same name as the database file with ".new" appended to the name. The database file is then overwritten and the temporary database file is deleted. The temporary database file will not be deleted if an error occurs while rewriting the database file.