gsk_create_database_signed

Creates a signed certificate as part of a set of certificates.

Format

   #include <gskcms.h>

   gsk_status gsk_create_database_signed_certificate (
                                    gsk_handle               db_handle,  
                                    const char *             ca_label,
                                    const char *             record_label,
                                    x509_algorithm_type      key_algorithm,  
                                    int                      key_size,   
                                    gsk_buffer *             key_parameters,  
                                    x509_algorithm_type      signature_algorithm,  
                                    const char *             subject_name, 
                                    int                      num_days, 
                                    gsk_boolean              ca_certificate,   
                                    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 key database and not a request database.
ca_label: Specifies the label of the certificate to be used to sign the new certificate. The key usage for the certificate must allow certificate signing. The label is specified in the local code page.
record_label: Specifies the label for the new database record. The label is specified in the local code page.
key_algorithm: Specifies the certificate key algorithm.
key_size: Specifies the certificate key size in bits.
key_parameters: Specifies the key generation parameters. Specify NULL for this parameter if the key algorithm does not require any key parameters.
signature_algorithm: Specifies the signature algorithm used for the certificate signature.
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.

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 key algorithm or 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 or CA certificate 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_EXPIRED]: The signer certificate is expired.
[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 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 read or write a database record.
[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.
[CMSERR_LABEL_NOT_UNIQUE]: The record label is not unique.
[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_NO_PRIVATE_KEY]: The signer certificate does not have a private key.
[CMSERR_RECORD_TOO_BIG]: The record is larger than the database record length.
[CMSERR_SUBJECT_IS_CA]: The requested subject name is the same as the signer name.
[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_database_signed_certificate() 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 certificate will be signed using an existing certificate as specified by the ca_label parameter and the signature algorithm specified by the signature_algorithm parameter.

If the specified certificate key is a Diffie-Hellman key, the signature_algorithm must specify either an RSA or a DSA signature.
If the specified certificate key is an ECC key, the signature_algorithm cannot specify a DSA signature.

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 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.
A DSS 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 new certificate will be stored in the key database using the supplied record label. The gsk_export_certificate() routine can be called to create an export file containing the certificate for transmission to another system.

The following key algorithms are supported:

x509_alg_rsaEncryption: RSA encryption - {1.2.840.113549.1.1.1}
x509_alg_idDsa: Digital Signature Standard (DSS) - {1.2.840.10040.4.1}
x509_alg_dhPublicNumber: Diffie-Hellman (DH) - {1.2.840.10046.2.1}
x509_alg_ecPublicKey: Elliptic Curve Public Key (ECC) - {1.2.840.10045.2.1}

RSA keys

Can be used for both CA certificates and end user certificates
Key size when not in FIPS mode is between 512 and 4096 bits rounded up to a multiple of 16
Key size in FIPS mode is between 1024 and 4096 bits rounded up to a multiple of 16
No key parameters

DSS keys

Can be used for both CA certificates and end user certificates.
Key sizes of between 512 and 1024 bits when in non-FIPS mode are rounded up to a multiple of 64.
Key sizes less than 1024 bits can only be generated in non-FIPS mode and are generated according to FIPS 186-2.
Key sizes of 1024 or 2048 bits are generated according to FIPS 186-3 in both FIPS mode and non-FIPS mode. These are the only valid key sizes in FIPS mode.
A key size of 1024 or less should specify x509_alg_dsaWithSha1 as the signature algorithm, while a key size of 2048 bits should specify either x509_alg_dsaWithSha224 or x509_alg_dsaWithSha256 as the signature algorithm.
Key parameters encoded as an ASN.1 sequence consisting of the prime p, the prime divisor q, and the generator g. For 1024-bit and 2048-bit keys, see FIPS 186-3: Digital Signature Standard (DSS) for more information about the key parameters, for smaller key sizes see FIPS 186-2: Digital Signature Standard (DSS). Note that key parameters that contain a p of 2048 bits and a q of 160 bits do not conform to FIPS 186-3 and are not supported. The gsk_generate_key_parameters() routine can be used to generate the key parameters.

DH keys

Can be used only for end user certificates
Can only be signed using a certificate containing either an RSA or DSA key
Key size when not in FIPS mode is between 512 and 2048 bits rounded up to a multiple of 64
Key size in FIPS mode of 2048 bits
Key parameters encoded as an ASN.1 sequence consisting of the prime P, the base G, and optionally the subprime Q and the subgroup factor J. See RFC 2631: Diffie-Hellman Key Agreement Method for more information about the key parameters for non-FIPS mode, and see z/OS Cryptographic Services ICSF Writing PKCS #11 Applications for FIPS mode. The gsk_generate_key_parameters() routine can be used to generate the key parameters.

ECC keys

Can be used for both CA certificates and end user certificates.
The ECC named curve used to generate the ECC key pair can be specified using either the key_parameters buffer or the key_size parameter. If the key_parameters buffer is supplied the key_size parameter will be ignored.
The key_parameters buffer must contain ASN.1 encoded ECC parameters, or be NULL.
If the key_parameters buffer is not supplied, the key_size parameter will be rounded up to the nearest supported key size and the default EC named curve for that key size will be used, as specified in Table 2.
In FIPS mode, only NIST recommended curves are supported.

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.

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.

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