z/OS Cryptographic Services System SSL Programming
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


gsk_add_record()

z/OS Cryptographic Services System SSL Programming
SC14-7495-00

Adds a record to a key or request database.

Format

   #include <gskcms.h>

   gsk_status gsk_add_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 key algorithm or 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_DUPLICATE_CERTIFICATE]
The database already contains the certificate.
[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_RECORD_TOO_BIG]
The record is larger than the database record length.
[CMSERR_RECTYPE_NOT_VALID]
The record type is not valid.
[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_add_record() routine adds a record to a key or request database. The database must be open for update in order to add records. Unused and reserved fields in the gskdb_record structure must be initialized to zero. An error will be returned when adding a certificate to a key database if the database already contains the certificate. 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

A unique record identifier is assigned when the record is added to the database and will be returned to the application in the recordId field. If the record contains an X.509 certificate, the issuerRecordId field will be set to the record identifier of the certificate issuer.

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 an X.509 certificate, the certificate will be validated and the record will not be added to the database if the validation check fails. If the database is a FIPS key database, then the certificate must use only FIPS algorithms and key sizes.

Except for the record label, all character strings are specified using UTF-8.

The database file is updated as part of the gsk_add_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.

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014