CPGenKey

The CPGenKey function generates a random cryptographic key or key pair.

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

Parameters

hProv

Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext.

Algid

Identifier for the algorithm for which the key is being 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:

• CALG_RC2
• CALG_RC4
• CALG_DES

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

• AT_KEYEXCHANGE
• AT_SIGNATURE

dwFlags

Flags specifying attributes pertaining to the key generated. The sizes of RSA signature and key exchange keys can 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 Base Cryptographic Provider. These are flags currently defined.

Flag value	Effect
CRYPT_EXPORTABLE	When a session key or private key is created and this flag is not set, the CSP must refuse to export the key. If the application attempts to export the key using CPExportKey, that function fails and returns the NTE_BAD_KEY_STATE error code. 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 set, the new session key is assigned a random salt value. If this flag is not set, the session key is assigned a salt value of zero. This flag does not apply to public/private key pairs.
CRYPT_NO_SALT	Specifies that a no salt value is assigned for 40-bit symmetric keys. For more information, see New Salt Value Functionality.
CRYPT_USER_ PROTECTED	When set, the CSP notifies the user through a dialog box or some other method when certain actions are attempted using this key. The precise behavior is specified by the CSP or the CSP type used. If the provider context was acquired with CRYPT_SILENT set, using this flag causes a failure and the last error is set to NTE_SILENT_CONTEXT The Microsoft Enhanced Cryptographic Provider supports this flag in Internet Explorer 4.0 and later, Windows 98, and Windows 2000. Prior to Internet Explorer 4.0, this flag was ignored.
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 copies a handle to the newly-generated key.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.

Remarks

An application cannot create new key pairs if no key container is currently open. This can happen if CRYPT_VERIFYCONTEXT was set in the CPAcquireContext call. If a key cannot be created, the NTE_PERM error code is returned.

CPGenRandom is generally used to generate the random key material.

Keys generated for symmetric block ciphers must be set up by default 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 using the CPSetKeyParam function.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 or later).
  Header: Declared in Wincrypt.h.

See Also

CPDestroyKey, CPExportKey, CPImportKey, CryptGenKey