Creates a signed certificate as part of a set of certificates.
This
function is deprecated. Use gsk_create_database_signed_certificate() instead.
Format
#include <gskcms.h>
gsk_status gsk_create_signed_certificate_set (
gsk_handle db_handle,
const char * ca_label,
const char * record_label,
x509_algorithm_type key_algorithm,
int key_size,
gsk_buffer * key_parameters,
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,
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.
- 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_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_signed_certificate_set() 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.
- If the specified certificate key is a Diffie-Hellman key, the
signing certificate must contain either an RSA or a DSA key.
- If the specified certificate key is an ECC key, the signing 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
- 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.
These 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 bits or less will use SHA1 digest, while a
key size of 2048 bits will use SHA256 digest.
- 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 a 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, 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 EC
domain 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
created 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_signed_certificate_set() 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.