|
Overview |
|
|
|
Group |
|
|
|
Quick Info
Windows NT
| Yes
| Win95
| OSR2
| Win32s
| No
| Import Library
| advapi32.lib
| Header File
| wincrypt.h
| Unicode
| WinNT
| Platform Notes
| None
|
|
|
CryptGenKey
[New - Windows NT]
[New - Windows 95, OEM Service Release 2]
The
CryptGenKey function generates random cryptographic keys for use with the CSP module. A
handle to the key is returned in
phKey. This handle can then be used as needed with any of the other CryptoAPI
functions requiring key handles.
The calling application is required to specify the algorithm when calling this
function. 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.
BOOL CRYPTFUNC CryptGenKey(
HCRYPTPROV hProv,
|
|
ALG_ID Algid,
|
|
DWORD dwFlags,
|
|
HCRYPTKEY *phKey
|
|
);
|
|
Parameters
hProv
[in] A handle to the application's CSP. An application obtains this handle
using the
CryptAcquireContext function.
Algid
[in] The identifier for the algorithm for which the key is to be generated.
The valid values for this parameter will vary, depending on the CSP that is
used. See the "Remarks" section for a list of possible algorithm identifiers.
dwFlags
[in] The flags specifying the type of key generated. This parameter can be
zero, or you can specify one or more of the following flags, using the binary OR
operator to combine them.
CRYPT_EXPORTABLE
If this flag is set, then the key can be transferred out of the CSP into a key
blob 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, then the key will
not be exportable. For a session key, this means that the key will only be
available 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 only applies 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, then the key will be assigned a random salt value
automatically. You can retrieve this salt value using the
CryptGetKeyParam function with the
dwParam parameter set to KP_SALT.
If this flag is not set, then the key will be given a salt value of zero.
When keys with non-zero salt values are exported (through
CryptExportKey), then the salt value must also be obtained and kept with the key blob.
CRYPT_USER_PROTECTED
If this flag is set, then the user will be notified through a dialog box or
another method when certain actions are attempted using this key. The precise
behavior is specified by the CSP being used.
The Microsoft RSA Base Provider ignores this flag.
phKey
[out] The address that the function copies the handle of the newly generated
key to.
Remarks
To generate a key to be used with a symmetric encryption algorithm (that is, a
session key), use the
Algid parameter to specify the algorithm. The algorithms available will most likely
be different for each CSP. If you are using the Microsoft RSA Base Provider,
one of the following values can be used to specify the algorithm:
- CALG_RC2
RC2 block cipher
- CALG_RC4
RC4 stream cipher
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.
To change these parameters, use the
CryptSetKeyParam function.
In addition to generating keys for symmetric algorithms, the
CryptGenKey function can also generate keys for public-key algorithms. The use of
public-key algorithms is restricted to key exchange and digital signatures. Each
CryptoAPI client generally possesses one key pair for each of these operations. To
generate one of these key pairs, set the
Algid parameter to one of the following values:
- AT_KEYEXCHANGE
Key exchange
- AT_SIGNATURE
Digital signature
Return Values
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To retrieve extended error
information, use the
GetLastError function.
The following table lists the error codes most commonly returned by the
GetLastError function. The error codes prefaced by "NTE" are generated by the particular
CSP you are using.
Error
| Description
|
ERROR_INVALID_HANDLE
| One of the parameters specifies an invalid handle.
|
ERROR_INVALID_PARAMETER
| One of the parameters contains an invalid value. This is most often an illegal
pointer.
|
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_BAD_UID
| The hProv parameter does not contain a valid context handle.
|
NTE_FAIL
| The function failed in some unexpected way.
|
Example
#include <wincrypt.h>
HCRYPTPROV hProv = 0;
HCRYPTKEY hKey = 0;
// Get handle to user default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
printf("Error %x during CryptAcquireContext!\n", GetLastError());
goto done;
}
// Create block cipher session key.
if(!CryptGenKey(hProv, CALG_RC2, CRYPT_EXPORTABLE, &hKey)) {
printf("Error %x during CryptGenKey!\n", GetLastError());
goto done;
}
// Use 'hKey' to do something.
...
done:
// Destroy session key.
if(hKey != 0) CryptDestroyKey(hKey);
// Release provider handle.
if(hProv != 0) CryptReleaseContext(hProv, 0);
See Also
CryptAcquireContext,
CryptDestroyKey,
CryptExportKey,
CryptGetKeyParam,
CryptImportKey,
CryptSetKeyParam
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database