gsk_construct_certificate()

Constructs a signed certificate and returns it to the caller.

Format

   #include <gskcms.h>

   gsk_status gsk_construct_certificate (
                                          pkcs_cert_key *             issuer_certificate,
                                          x509_algorithm_type         signature_algorithm,
                                          const char *                subject_name,
                                          int                         num_days,
                                          gsk_boolean                 ca_certificate,
                                          x509_extensions *           extensions,
                                          x509_public_key_info *      public_key,
                                          x509_certificate *          subject_certificate)

Parameters

issuer_certificate: Specifies the issuing CA certificate with private key.
signature_algorithm: Specifies the signature algorithm for the certificate.
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.
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.
extensions: Specifies the certificate extensions for the new certificate. Specify NULL for this parameter if no certificate extensions are supplied.
public_key: Specifies the public key for the constructed certificate.
subject_certificate: Contains the constructed certificate.

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_BAD_EC_PARAMS]: Elliptic Curve parameters are not valid.
[CMSERR_BAD_KEY_SIZE]: The key size is not valid.
[CMSERR_BAD_SUBJECT_NAME]: The subject name is not valid.
[CMSERR_CA_NOT_SUPPLIED]: Signing Certificate Authority Certificate not supplied.
[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_EXPIRED]: The signer 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_KEY_TYPE]: Incorrect key algorithm.
[CMSERR_INCORRECT_KEY_USAGE]: The signer certificate key usage does not allow signing certificates.
[CMSERR_ISSUER_NOT_CA]: The signer certificate is not for a certification authority.
[CMSERR_KEY_MISMATCH]: The signer certificate key cannot be used to sign a certificate or the key type is not supported for the requested signature algorithm.
[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_NO_PRIVATE_KEY]: The signer certificate does not have a private key.
[CMSERR_SUBJECT_IS_CA]: The requested subject name is the same as the signer name.

Usage

The gsk_construct_certificate() routine will construct an X.509 certificate as described in RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile. The certificate will be signed using the certificate as supplied by the issuer_certificate parameter.

If the supplied public_key contains a Diffie-Hellman key, the issuer_certificate must contain either an RSA or a DSA key.
If the supplied public_key is an ECC key, the issuer_certificate cannot contain a DSA key.

A certification authority (CA) 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 as follows:

An RSA key can be used for authentication, digital signature, and data encryption. An RSA key can be used for both CA certificates and end user certificates.
A DSS key can be used for authentication and digital signature. A DSS key can be used for both CA certificates and end user certificates.
A Diffie_Hellman key can be used for key agreement. A Diffie-Hellman key can be used only for end user certificates.
An ECC key can be used for authentication, digital signature and key agreement. An ECC key can be used for both CA certificates and end user certificates.

The new certificate is returned in the supplied x509_certificate structure.

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.

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 constructed for the certificate, however a SubjectKeyIdentifier extension provided by the application will be ignored.