CPGenKey

The CPGenKey function generates random cryptographic keys.

BOOL CPGenKey(
  HCRYPTPROV hProv, // in
  ALG_ID Algid,     // in
  DWORD dwFlags,    // in
  HCRYPTKEY *phKey  // out
);

Parameters

hProv
Handle to a particular key container (or "context") within the CSP. This handle is obtained via a call to CPAcquireContext.
Algid
Identifier for the algorithm for which the key is to be generated. This algorithm must be one of those supported by this CSP.

If a session key is to be generated, this value specifies an encryption algorithm, such as:

If a public/private key pair is to be generated, this value specifies a key pair type, such as:

dwFlags
Flags specifying attributes pertaining to the key generated. The sizes of RSA signature and key exchange keys may be set when the key is generated. The key size is set with the upper 16 bits of the dwFlags parameter and these 16 bits represent the length of the modulus in bits. This applies to the Microsoft Cryptographic Base Provider.The flags currently defined are:
CRYPT_EXPORTABLE
When a session key is created and this flag is not set, the CSP should refuse to export the key. If the application attempts to export the key (via CPExportKey) then the NTE_BAD_KEY_STATE error code should be returned.

This flag only applies to the export of session keys and private keys. It does not apply to public keys, which are always exportable.

CRYPT_CREATE_SALT
When this flag is set, the new session key will be assigned a random salt value automatically.

If this flag is not set, then the session key will be given a salt value of zero.

This flag does not apply to public/private key pairs.

CRYPT_NO_SALT
Specifies that a no salt value gets allocated for a 40-bit symmetric key. For more information, see Microsoft Cryptographic Providers--Release Notes.
CRYPT_USER_PROTECTED
When this flag is set, the CSP is to notify the user directly, via a dialog box or some other method, when certain actions are attempted using this key. The precise behavior is specified by the CSP (or possibly the CSP type) that is used. Prior to Microsoft Internet Explorer 4.0, the Microsoft Cryptographic Providers ignore this flag. Starting with Microsoft Internet Explorer 4.0, Microsoft Providers support this flag value.
CRYPT_PREGEN
Specifies an initial Diffie-Hellman or DSS key generation. Currently only useful with Diffie-Hellman/DSS CSPs.
phKey
Address to which the function is to copy a handle to the newly generated key.

Return Values

If the function succeeds, TRUE should be returned; otherwise, return FALSE. When FALSE is returned, the appropriate error code (see the following table) must be set via SetLastError.

Error Description
NTE_BAD_ALGID The Algid parameter specifies an algorithm that this CSP does not support.
NTE_BAD_FLAGS The dwFlags parameter contains an invalid value.
NTE_FAIL The function failed in some unexpected way.
NTE_BAD_UID The hProv parameter does not contain a valid context handle.
NTE_PERM An attempt was made to create a key pair when CRYPT_VERIFYCONTEXT was specified.

Remarks

If no key container is currently open (for example, the CRYPT_VERIFYCONTEXT flag was set in the CPAcquireContext call), then applications should not be allowed to create new key pairs. Instead, the NTE_PERM error code should be returned.

The CPGenRandom function is generally used to generate the random key material. It is important that all keys generated be truly random.

When keys are generated for symmetric block ciphers, the key by default will be set up in cipher block chaining (CBC) mode with an initialization vector of zero. This cipher mode provides a good default method for bulk encrypting data. These parameters are changed by using the CPSetKeyParam function.

See Also

CPDestroyKey, CPExportKey, CPImportKey, CryptGenKey