gsk_encode_export

Encodes an X.509 certificate and its private key into a PKCS #12 data stream.

Format

   #include <gskcms.h>

   gsk_status gsk_encode_export_key (
                                          pkcs_cert_key *      subject_certificate,
                                          pkcs_certificates *  issuer_certificates,
                                          gskdb_export_format  format,
                                          x509_algorithm_type  algorithm,
                                          const char *         password,
                                          const char *         nickname,
                                          gsk_buffer *         stream)

Parameters

subject_certificate

Specifies the certificate and key.

issuer_certificates

Specifies the certificate chain for the subject certificate.

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:

x509_alg_pbeWithSha1And40BitRc2Cbc: 40bit RC2 with SHA-1 digest.
x509_alg_pbeWithSha1And128BitRc2Cbc: 128-bit RC2 with SHA-1 digest.
x509_alg_pbeWithSha1And40BitRc4: 40bit 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, the only supported encryption algorithm for the export file is:

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 encoded for export is a secure private key in the TKDS, the maximum password length is 63 bytes.

nickname

Specifies the nickname assigned to the exported key in the bagAttributes field for a PKCS #12 Version 1 format file. The nickname is in the local code page. It may not be an empty string. If a PKCS #12 Version 3 export file format is specified, this parameter is ignored.

stream

Returns the byte stream for the encoded certificate. The application should call the gsk_free_buffer() function 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 signature algorithm is not valid.
[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_PW_INCORRECT]: The password is not correct.

Usage

The gsk_encode_export_key() function encodes an X.509 certificate and its private key into a PKCS #12 data stream. The certificate chain for the subject certificate is supplied from the pkcs_certificates structure issuer_certificates, with the root certificate being the final entry in the array.

The export byte stream contains the requested certificate, its private key, and the certification chain. A partial certification chain is exported if the complete chain is not supplied in issuer_certificates.

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.