gsk_create_signed_certificate

Creates a signed certificate.

Format

   #include <gskcms.h>

   gsk_status gsk_create_signed_certificate_record (
                              gsk_handle            db_handle,  
                              const char *          label,   
                              int                   num_days,   
                              gsk_boolean           ca_certificate,  
                              x509_algorithm_type   signature_algorithm,
                              x509_extensions *     extensions,
                              gsk_buffer *          cert_request,
                              gsk_buffer *          signed_certificate)

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. This must be a key database and not a request database.
label: Specifies the label for the certificate to be used to sign the new certificate. The label is specified in the local code page.
num_days: Specifies the number of days for the certificate validity period as a value between 1 and 9999 (the maximum of 9999 will be used if a larger value is specified and the minimum of 1 will be used if a smaller value is specified).
ca_certificate: Specify TRUE if this is a certification authority certificate or FALSE if this is an end user certificate.
signature_algorithm: Specifies the signature algorithm to be used for the certificate signature.
extensions: Specifies the certificate extensions for the new certificate. Specify NULL for this parameter if no certificate extensions are supplied.
cert_request: Specifies the PKCS #10 certification request stream in either binary DER-encoded format or in Base64 format. A Base64 stream is in the local code page.
signed_certificate: Returns the signed certificate in Base64 format. The Base64 stream will be in the local code page. The application should call the gsk_free_buffer() routine to release the certificate stream 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_BACKUP EXISTS]: The backup file already exists.
[CMSERR_BAD_EC_PARAMS]: Elliptic Curve parameters are not valid.
[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_SUBJECT_NAME]: The subject name is not valid.
[CMSERR_DUPLICATE_EXTENSION]: Supplied extensions contain a duplicate extension.
[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 database type does not support certificates.
[CMSERR_INCORRECT_KEY_TYPE]: Incorrect key algorithm.
[CMSERR_INCORRECT_KEY_USAGE]: The signer certificate key usage does not allow signing certificates
[CMSERR_IO_ERROR]: Unable to write record.
[CMSERR_KEY_MISMATCH]: The signer certificate key cannot be used to sign a certificate or the signers key type is not supported for the requested signature algorithm.
[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_signed_certificate_record() routine will generate an X.509 certificate as described in RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile. The new certificate will be signed using the certificate specified by the label parameter and the signature algorithm specified by the signature_algorithm parameter.

If the certificate request contains an ECC key, the signing certificate cannot contain a DSA key.

The following 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. A DSA key size must be between 512 and 2048 bits. A key size of 1024 or less should specify signature algorithm x509_alg_dsaWithSha1, and 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. 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, and a key size of 2048 bits should specify either x509_alg_dsaWithSha224 or x509_alg_dsaWithSha256 as the signature algorithm. An ECC key must use a NIST recommended EC named curve.

A certification authority certificate will have basic constraints and key usage extensions which allow the certificate to be used to sign other certificates and certificate revocation lists. An end user certificate will have basic constraints and key usage extensions which allow the certificate to be used as follows:

An RSA key can be used for authentication, digital signature, and data encryption.
A DSA key can be used for authentication and digital signature.
A Diffie-Hellman key can be used for key agreement.
An ECC key can be used for authentication, digital signature and key agreement.

The certificate expiration date will be set to the earlier of the requested expiration date and the expiration date of the signing certificate.

The signing certificate must have an associated private key, the BasicConstraints extension must either be omitted or must have the CA indicator set, and the KeyUsage extension must either be omitted or must allow signing certificates.

A CA certificate will have SubjectKeyIdentifier, KeyUsage, and BasicConstraints extensions while an end user certificate will have SubjectKeyIdentifier and KeyUsage extensions. An AuthorityKeyIdentifier extension will be created if the signing certificate has a SubjectKeyIdentifier extension. The application can supply additional extensions through the extensions parameter. An AuthorityKeyIdentifier, KeyUsage, or BasicConstraints extension provided by the application will replace the default extension created for the certificate, however a SubjectKeyIdentifier extension provided by the application will be ignored.

Certificate extensions can also be contained within the certification request. A certificate extension supplied by the application will override a certificate extension of the same type contained in the certification request. The certificate extensions found in the certification request will be copied unmodified to the new certificate with these exceptions:

The AuthorityInfoAccess, AuthorityKeyIdentifier, BasicConstraints, CrlDistributionPoints, IssuerAltName, NameConstraints, PolicyConstraints, PolicyMappings, and PrivateKeyUsagePeriod extensions will not be copied
The keyCertSign and crlSign flags in the KeyUsage extension will be modified based upon the value of the ca_certificate parameter.

No certification path validation is performed by the gsk_create_signed_certificate_record() routine. An error will be returned if the requested subject name is the same as the subject name in the signing certificate.