gsk_import

Imports a certificate and associated private key.

Format

   #include <gskcms.h>

   gsk_status gsk_import_key (   
                               gsk_handle           db_handle, 
                               const char *         label,
                               const char *         password,  
                               gsk_buffer *         stream)

Parameters

db_handle: Specifies the database handle returned by the gsk_create_database() routine or the gsk_open_database() routine.
label: Specifies the label for the new database record. The label is specified in the local code page.
password: Specifies the password for the import file. The password is in the local code page and must consist of characters which can be represented using 7-bit ASCII (letters, numbers, and punctuation). It may not be an empty string. The user will be prompted to enter the password if NULL is specified for this parameter.
stream: Specifies the byte stream for the encoded certificate and private key.

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_BASE64_ENCODING]: The Base64 encoding of the import file is not correct.
[CMSERR_BAD_ENCODING]: The import file format is not recognized.
[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_SIGNATURE]: The certificate signature is not correct.
[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_EXPIRED]: The certificate is expired.
[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 database type does not support certificates.
[CMSERR_INCORRECT_KEY_USAGE]: The issuer certificate does not allow signing certificates.
[CMSERR_ISSUER_NOT_CA]: The certificate issuer is not a certification authority.
[CMSERR_ISSUER_NOT_FOUND]: The issuer certificate is not in the key database.
[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_NOT_YET_VALID]: The certificate is not yet valid.
[CMSERR_RECORD_TOO_BIG]: The record is larger than the database record length.
[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_import_key() routine imports an X.509 certificate and its private key and creates a new database record. An error will be returned if the database already contains the certificate. The database must be open for update in order to import certificates.

The certificate and key must have been encoded according to the Personal Information Exchange Syntax (PKCS #12). If executing in FIPS mode, the only supported encryption is the x509_alg_pbeWithSha1And3DesCbc algorithm. The supplied stream can be the binary ASN.1 sequence or the Base64 encoding of the ASN.1 sequence. A Base64 encoded stream is assumed to be in the local code page and must include the encoding header and footer lines.

The record label is used as a friendly name for the database entry. It can be any value and consists of characters which can be represented using 7-bit ASCII (letters, numbers, and punctuation). It may not be an empty string. An error will be returned if the certificate already exists in the key database or the record label is not unique.

A unique record identifier is assigned when the record is added to the database. The certificate signature will be verified using the certificate of the issuer. The certificate will be marked as a trusted certificate when it is added to the database.

Each certificate in the certification chain will be imported if it is present in the import file. The certificate subject name will be used as the label for certificates added from the certification chain. A chain certificate will not be added to the database if the label is not unique or if the certificate is already in the database.

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