gsk_export

Exports a certificate and the associated private key.

Format

   #include <gskcms.h>

   gsk_status gsk_export_key (  
                                         gsk_handle           db_handle,
                                         const char *         label,
                                         gskdb_export_format  format,
                                         x509_algorithm_type  algorithm,
                                         const char *         password,
                                         gsk_buffer *         stream,)

Parameters

db_handle

Specifies the database handle returned by the gsk_create_database() routine, the gsk_open_database() routine, or the gsk_open_keyring() routine. The database must be a key database and not a request database. For a SAF key ring database, the private key must be stored in the SAF database and not in ICSF.

label

Specifies the label for the database record. The label is specified in the local code page.

format

Specifies the export format. These values may be specified:

gskdb_export_pkcs12v1_binary: Binary PKCS #12 Version 1
gskdb_export_pkcs12v1_base64: Base64 PKCS #12 Version 1
gskdb_export_pkcs12v3_binary: Binary PKCS #12 Version 3
gskdb_export_pkcs12v3_base64: Base64 PKCS #12 Version 3

algorithm

Specifies the encryption algorithm for the export file. The strong encryption algorithms may not be available depending upon government export regulations.

These values may be specified for the PKCS #12 Version 1 format:

x509_alg_pb1WithSha1And40BitRc2Cbc: 40-bit RC2 with SHA-1 digest
x509_alg_pb1WithSha1And128 BitRc2Cbc: 128bit RC2 with SHA-1 digest
x509_alg_pb1WithSha1And40BitRc4: 40-bit RC4 with SHA-1 digest
x509_alg_pb1WithSha1And128BitRc4: 128-bit RC4 with SHA-1 digest
x509_alg_pb1WithSha1And3DesCbc: Triple DES with SHA-1 digest

These values may be specified for the PKCS #12 Version 3 format:

x509_alg_pbeWithSha1And40BitRc2Cbc: 40-bit RC2 with SHA-1 digest
x509_alg_pbeWithSha1And128 BitRc2Cbc: 128bit RC2 with SHA-1 digest
x509_alg_pbeWithSha1And40BitRc4: 40-bit RC4 with SHA-1 digest
x509_alg_pbeWithSha1And128BitRc4: 128-bit RC4 with SHA-1 digest
x509_alg_pbeWithSha1And3DesCbc: Triple DES with SHA-1 digest

In FIPS mode, there is only one supported encryption algorithm for the export file.

For PKCS #12 Version 3:

x509_alg_pbeWithSha1And3DesCbc: Triple DES with SHA-1 digest.

password

Specifies the password for the export 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 is prompted to enter the password if NULL is specified for this parameter. If the key that is being exported is a secure private key in the TKDS, the maximum password length is 63 bytes.

stream

Return the byte stream for the encoded certificate. The application should call the gsk_free_buffer() routine to release the storage when it is no longer needed.

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 encryption algorithm is not supported.
[CMSERR_BAD_HANDLE]: The database handle is not valid.
[CMSERR_BAD_LABEL]: The record label or CA certificate label is not valid.
[CMSERR_BAD_RNG_OUTPUT]: In FIPS mode, random bytes generation produced duplicate output.
[CMSERR_CRYPTO_HARDWARE_NOT_AVAILABLE]: Cryptographic hardware does not support service or algorithm.
[CMSERR_FMT_NOT_SUPPORTED]: An unsupported export file format is specified.
[CMSERR_ICSF_FIPS_BAD_ALG_OR_KEY_SIZE]: The algorithm or key size is not supported by ICSF in FIPS mode.
[CMSERR_ICSF_FIPS_DISABLED]: ICSF PKCS #11 services are disabled.
[CMSERR_ICSF_NOT_FIPS]: ICSF is not operating in FIPS mode.
[CMSERR_INCORRECT_DBTYPE]: The database type does not support certificates.
[CMSERR_INCORRECT_KEY_ATTRIBUTE]: Parameter contents or key attribute value is incorrect.
[CMSERR_KEY_CANNOT_BE_EXTRACTED]: PKCS #11 key cannot be extracted.
[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_NO_PRIVATE_KEY]: The signer certificate does not have a private key.
[CMSERR_RECORD_NOT_FOUND]: The requested record is not found.

Usage

The gsk_export_key() routine exports an X.509 certificate and the associated private key. The certificate can be exported using either the PKCS #12 Version 1 format or the PKCS #12 Version 3 format. This can be either the binary value or the Base64 encoding of the binary value. A Base64 encoded stream will be in the local code page and will include the encoding header and footer lines.

The PKCS #12 Version 1 format is obsolete. However, it is the only format supported by some SSL implementations and must be used when moving a certificate and key to one of those systems. If not running in FIPS mode, you should use either x509_alg_pb1WithSha1And40BitRc2Cbc or x509_alg_pb1withSha1And3DesCbc for interoperability with these older SSL implementations.

The export file will contain the requested certificate, its private key, and the certification chain. A partial certification chain will be exported if the complete chain is not in the database.

If the certificate's private key is stored as a secure TKDS private key label:

Only formats gskdb_export_pkcs12v3_binary and gskdb_export_pkcs12v3_base64, along with algorithm x509_alg_pbeWithSha1And3DesCbc, are supported.
When the private key was created in the TKDS, it was created with the extractable attribute.
When using this API, you must have the correct access to the CRYPTOZ class. See Using cryptographic features with System SSL for more information.