gsk_generate_key

Generates a public/private key pair.

Format

   #include <gskcms.h>

   gsk_status gsk_generate_key_pair (
                             x509_algorithm_type          key_algorithm,
                             int                          key_size,
                             gsk_buffer *                 key_params, 
                             x509_public_key_info *       public_key,
                             pkcs_private_key_info *      private_key,
                             gsk_buffer *                 key_identifier)

Parameters

key_algorithm: Specifies the key algorithm.
key_size: Specifies the key size in bits.
key_params: Specifies the key parameters as an ASN.1-encoded sequence. Specify NULL for this parameter if the key algorithm does not require any parameters.
public_key: Returns the generated public key. The application should call the gsk_free_public_key_info() routine to release the public key when it is no longer needed.
private_key: Returns the generated private key. The application should call the gsk_free_private_key_info() routine to release the private key when it is no longer needed.
key_identifier: Returns the key identifier for the generated public key. The application should call the gsk_free_buffer() routine to release the key identifier when it is no longer needed. Specify NULL for this parameter if the key identifier is not 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 key algorithm is not supported.
[CMSERR_BAD_DH_PARAMS]: The Diffie-Hellman group parameters are not valid.
[CMSERR_BAD_DSA_PARAMS]: The DSS parameters are not valid.
[CMSERR_BAD_EC_PARAMS]: Elliptic Curve parameters are not valid.
[CMSERR_BAD_KEY_SIZE]: The key size is not valid.
[CMSERR_ECURVE_NOT_FIPS_APPROVED]: Elliptic Curve not supported in FIPS mode.
[CMSERR_ECURVE_NOT_SUPPORTED]: Elliptic Curve is not supported.
[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_NO_MEMORY]: Insufficient storage is available.

Usage

The gsk_generate_key_pair() routine will generate a public/private key pair. The format of the public and private key values returned by the gsk_generate_key_pair() routine is defined in RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

These key algorithms are supported:

x509_alg_rsaEncryption - RSA Encryption - {1.2.840.113549.1.1.1}
The key size must be between 512 and 4096 bits if not executing in FIPS mode, and must be between 1024 and 4096 bits if executing in FIPS mode, and will be rounded up to a multiple of 16 bits if necessary. No key parameters are used. The key size determines the size of the modulus N.
x509_alg_idDsa - Digital Signature Standard - {1.2.840.10040.4.1}
The key size can be between 512 and 1024 bits, which will be rounded up to a multiple of 64 bits, or precisely 2048 bits. Key sizes less than 1024 bits can only be generated in non-FIPS mode and are generated according to FIPS 186-2: Digital Signature Standard (DSS). Keys sizes 1024 and 2048 are generated according to FIPS 186-3: Digital Signature Standard (DSS). The key parameters are the prime p, the prime divisor q, and the generator g. The requested key size must be the same as the size of the prime p. 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.
x509_alg_dhPublicNumber - Diffie-Hellman Key Exchange - {1.2.840.10046.2.1}
The key size must be between 512 and 2048 bits if not executing in FIPS mode, and must be 2048 bits if executing in FIPS mode, and will be rounded up to a multiple of 64 bits if necessary. The key parameters are the prime P, the base G, the subprime Q, and the subgroup factor J. The requested key size must be the same as the size of the prime P. The gsk_generate_key_parameters() routine can be used to generate the key parameters.

In non-FIPS mode, the subprime Q and the subgroup factor J are optional key parameters. This allows the gsk_generate_key_pair() routine to accept key parameters generated in accordance with PKCS #3 (Diffie-Hellman Key Agreement Standard) including key parameters generated in accordance with RFC 2631: Diffie-Hellman Key Agreement Method. The private value X will be less than Q-1 if Q is present in the key parameters, otherwise the private value X will be less than P-1.

Multiple Digital Signature Standard keys or Diffie-Hellman Key Exchange keys can share the same group parameters (P, Q, and G). This is useful when generating multiple keys of the same type since it is very time-consuming to compute values for P, Q, and G. In addition, the Diffie-Hellman key agreement algorithm requires both parties to use the same group parameters when computing the secret value.
x509_alg_ecPublicKey – ECDSA and ECDH Public Key - {1.2.840.10045.2.1}
The EC named curve used to generate the ECC key pair can be specified using either the key_params buffer or the key_size parameter. If the key_params buffer is supplied, the key_size parameter will be ignored. The key_params buffer must contain ASN.1 encoded EC domain parameters, or be NULL. If the key_params buffer is NULL, 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.