CryptGenKey

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function generates a random cryptographic session key or a public/private key pair for use with the cryptographic service provider (CSP). The function retrieves a handle to the key in the phKey parameter. This handle can then be used as needed with any of the other CryptoAPI functions requiring a key handle.

When calling this function, the application must specify the algorithm. Because this algorithm type is kept bundled with the key, the application does not need to specify the algorithm later when the actual cryptographic operations are performed.

Syntax

BOOL CRYPTFUNC CryptGenKey( 
  HCRYPTPROV hProv, 
  ALG_ID Algid,
  DWORD dwFlags, 
  HCRYPTKEY* phKey
);

Parameters

• hProv
  [in] HCRYPTPROV handle to a CSP created by a call to CryptAcquireContext.

• Algid
  [in] ALG_ID identifier of the algorithm for the key to be generated. For more information about the Algid parameter, see the Remarks section.

• dwFlags
  [in] Flags describing the type of key generated, or zero. The following table shows flags that you can specify. You can use the bitwise OR operator to combine flags. For information about setting key size using this parameter, see the Remarks section.

  Flag	Description
  CRYPT_EXPORTABLE	If this flag is set, the key can be transferred out of the CSP into a key BLOB by using the CryptExportKey function. Because session keys generally must be exportable, this flag should usually be set when they are created. If this flag is not set, the key will not be exportable. For a session key, this means that the key will be available only within the current session and only the application that created it will be able to use it. For a public/private key pair, this means that the private key cannot be transported or backed up. This flag applies only to session key and private key BLOBs. It does not apply to public keys, which are always exportable.
  CRYPT_CREATE_SALT	If this flag is set, the key will be assigned a random salt value automatically. You can retrieve this salt value by using the CryptGetKeyParam function with the dwParam parameter set to KP_SALT. If this flag is not set, the key will be given a salt value of zero. When keys with nonzero salt values are exported through CryptExportKey, the salt value must also be obtained and kept with the key BLOB.
  CRYPT_NO_SALT	Specifies that a no salt value gets allocated for a 40-bit symmetric key.
  CRYPT_USER_PROTECTED	The Microsoft cryptographic service providers ignore this flag.
  CRYPT_PREGEN.	Specifies an initial Diffie-Hellman or DSS key generation. Useful only with Diffie-Hellman/DSS CSPs.

• phKey
  [out] Pointer to an HCRYPTKEY handle to the newly generated key.

Return Value

TRUE indicates success. FALSE indicates failure. To get extended error information, call the GetLastError function.

The following table describes the common values for the GetLastError function. The error values prefaced by NTE are generated by the particular CSP you are using.

Remarks

To generate a session key to be used with a symmetric encryption algorithm, use the Algid parameter to specify the algorithm. The valid values for this parameter vary depending on the CSP. See ALG_ID for identifier definitions.

In addition to generating keys for symmetric algorithms, the CryptGenKey function can generate keys for public/private key pair algorithms. The use of public/private key pair algorithms is restricted to key exchange and digital signatures, with key specifications AT_KEYEXCHANGE and AT_SIGNATURE, respectively. Each CryptoAPI client generally possesses one key pair for each of these operations. The algorithm identifier that is used to generate a key depends on the provider used. As a result, for these key specifications, the values retrieved by the CryptGetKeyParam function, with the KP_ALGID key type specified for the dwParam parameter, depend on the provider used.

When keys are generated for symmetric block ciphers, the key is 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 data encryption. To change these parameters, use the CryptSetKeyParam function.

The size of a key can be set when the key is generated. The key size is set with the upper 16 bits of the dwFlags parameter, which represent the length of the key, or modulus. For example, if a 2048-bit RSA signature key is to be generated, then the value 0x08000000 is combined with the dwFlags parameter in a bitwise OR operation. Notice that the upper 16 bits of 0x08000000 is 0x0800, or 2048 in decimal notation. If none of the upper 16 bits are set, the default key size is generated. If a key is given that is larger than the maximum key size or smaller than the minimum size, the call fails with ERROR_INVALID_PARAMETER. **

To choose an appropriate key length, the following methods are recommended:

• Enumerate the algorithms that the CSP supports and get the maximum and minimum key lengths for each algorithm.
• Use the minimum and maximum lengths to choose an appropriate key length. It is not always advisable to choose the maximum length because this can lead to performance issues.
• After choosing the desired key length, use the upper 16 bits of the dwFlags parameter to specify the length.

Example Code

#include <wincrypt.h>
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
// Get a handle to user default provider.
// Call CryptAcquireContext. For sample code, see <A HREF="wce50lrfcryptacquirecontext.htm">CryptAcquireContext</A>.
// Create a block cipher session key.
if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {
 printf("Error %x during CryptGenKey!\n", GetLastError());
 goto done;
}
// Use 'hKey' to encrypt or decrypt a message.
...
done:
// Destroy the session key.
if(hKey != 0) CryptDestroyKey(hKey);
// Free the provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);
 

Requirements

See Also

Reference

ALG_ID
CryptAcquireContext
CryptDestroyKey
CryptExportKey
CryptGetKeyParam
CryptImportKey
CryptSetKeyParam