gsk_create_certification

Creates a PKCS #10 certification request as described in PKCS #10, Version 1.7: Certification Request.

Format

   #include <gskcms.h>

   gsk_status gsk_create_certification_request ( 
                                                 gsk_handle                  db_handle, 
                                                 const char *                label, 
                                                 x509_algorithm_type         signature_algorithm,  
                                                 int                         key_size, 
                                                 const char *                subject_name, 
                                                 x509_extensions *           extensions)

Parameters

db_handle: Specifies the database handle returned by the gsk_create_database() routine or the gsk_open_database() routine. This must be a request database and not a key database.
label: Specifies the label for the new database record. The label is specified in the local code page.
signature_algorithm: Specifies the signature algorithm for the certificate.
key_size: Specifies the key size in bits.
subject_name: Specifies the distinguished name for the certificate subject. The distinguished name is specified in the local code page and consists of one or more relative distinguished name components separated by commas.
extensions: Specifies certificate extensions to be included in the certification request. Specify NULL for this parameter if no certificate extensions are provided.

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_FIPS_KEY_PAIR_CONSISTENCY]: FIPS mode key generation failed pair-wise consistency check.
[CMSERR_ICSF_CLEAR_KEY_SUPPORT_NOT_AVAILABLE]: Clear key support not available due to ICSF key policy.
[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 certification requests.
[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_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_create_certification_request() routine creates a PKCS #10 certification request. The request is then stored in the request database. The gsk_export_certification_request() routine can be called to create an export file containing the request for transmission to the certification authority.

The gsk_create_certification_request() routine is similar to the gsk_create_renewal_request() routine. Both routines create a PKCS #10 certification request. The difference is the gsk_create_certification_request() routine generates a new public/private key pair while the gsk_create_renewal_request() routine uses the public/private key pair provided by the application.

These signature algorithms are supported:

x509_alg_md2WithRsaEncryption: RSA encryption with MD2 digest - {1.2.840.113549.1.1.2}
x509_alg_md5WithRsaEncryption: RSA encryption with MD5 digest - {1.2.840.113549.1.1.4}
x509_alg_sha1WithRsaEncryption: RSA encryption with SHA-1 digest - {1.2.840.113549.1.1.5}
x509_alg_sha224WithRsaEncryption: RSA encryption with SHA-224 digest - {1.2.840.113549.1.1.14}
x509_alg_sha256WithRsaEncryption: RSA encryption with SHA-256 digest - {1.2.840.113549.1.1.11}
x509_alg_sha384WithRsaEncryption: RSA encryption with SHA-384 digest - {1.2.840.113549.1.1.12}
x509_alg_sha512WithRsaEncryption: RSA encryption with SHA-512 digest - {1.2.840.113549.1.1.13}
x509_alg_dsaWithSha1: Digital Signature Standard with SHA-1 digest - {1.2.840.10040.4.3}
x509_alg_dsaWithSha224: Digital Signature Standard with SHA-224 digest – {2.16.840.1.101.3.4.3.1}
x509_alg_dsaWithSha256: Digital Signature Standard with SHA-256 digest – {2.16.840.1.101.3.4.3.2}
x509_alg_ecdsaWithSha1: Elliptic Curve Digital Signature Algorithm with SHA-1 digest - {1.2.840.10045.4.1}
x509_alg_ecdsaWithSha224: Elliptic Curve Digital Signature Algorithm with SHA-224 digest - {1.2.840.10045.4.3.1}
x509_alg_ecdsaWithSha256: Elliptic Curve Digital Signature Algorithm with SHA-256 digest - {1.2.840.10045.4.3.2}
x509_alg_ecdsaWithSha384: Elliptic Curve Digital Signature Algorithm with SHA-384 digest - {1.2.840.10045.4.3.3}
x509_alg_ecdsaWithSha512: Elliptic Curve Digital Signature Algorithm with SHA-512 digest - {1.2.840.10045.4.3.4}

When executing in FIPS mode, signature algorithms x509_alg_md2WithRSAEncryption and x509_alg_md5WithRsaEncryption are not supported.

If not in FIPS mode, an RSA key size must be between 512 and 4096 bits and will be rounded up to a multiple of 16 bits. A DSA key size must be between 512 and 2048 bits. Key sizes of between 512 and 1024 bits are rounded up to a multiple of 64, key size 2048 must be explicitly specified as such. A key size of 1024 or less should specify signature algorithm x509_alg_dsaWithSha1, while a key size of 2048 bits should specify either x509_alg_dsaWithSha224 or x509_alg_dsaWithSha256 as the signature algorithm.

In FIPS mode, an RSA key size must be between 1024 and 4096 bits and will be rounded up to a multiple of 16 bits. A DSA key size must be either 1024 bits or 2048 bits. A key size of 1024 bits should specify signature algorithm x509_alg_dsaWithSha1, while a key size of 2048 bits should specify either x509_alg_dsaWithSha224 or x509_alg_dsaWithSha256 as the signature algorithm.

For an ECC key the key size will determine the default named curve that will be used for the public/private key pair, as specified in Table 2. In FIPS mode, only NIST recommended that curves are supported. To specify a specific supported elliptic curve, use gsk_construct_renewal_request() to create a certificate request.

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.

The extensions parameter can be used to provide certificate extensions for inclusion in the certification request. Whether or not a particular certificate extension will be included in the new certificate is determined by the certification authority.

The database must be open for update in order to add the new request. The database file is updated as part of the gsk_create_certification_request() 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.