CPDeriveKey

The CPDeriveKey function generates a cryptographic session key using a hash of base data. This function guarantees that all keys generated from the same base data using the same algorithms will be identical. The base data can be a password or other user-supplied data.

BOOL CPDeriveKey(
  HCRYPTPROV  hProv,        // in
  ALG_ID      Algid,        // in
  HCRYPTHASH  hBaseData,    // 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 of the encryption algorithm for which the key is to be generated. This algorithm must be one of those supported by the CSP.

The following Algid values are used with Schannel providers.

Algid	Meaning
CALG_SCHANNEL_ ENC_KEY	Generates a bulk encryption key. The key generation algorithm and key size must have been previously specified with a call to the CPSetKeyParam function. The initialization vector (IV) is typically set using CPSetKeyParam with KP_IV. Some protocol and cipher suite combinations insist on building the IV from the key block. In this case, the CSP derives the IV automatically. For SSL 2, this key is also used as the MAC key.
CALG_SCHANNEL_ MAC_KEY	Generates a MAC key. The key generation algorithm has previously been specified with a call to CPSetKeyParam.

hBaseData

Handle to a hash object that contains a hash of the base data.

dwFlags

Attributes of the session key generated. Not all CSPs support all flags. Currently defined flags are listed below.

Flag value	Meaning
CRYPT_EXPORTABLE	The session key can be transferred out of the CSP into a key BLOB using CPExportKey. Because keys generally must be exportable, this flag is usually set. If this flag is not set, the session key is not exportable. The session key is available only within the current session and can only be used by the application that created it. This flag does not apply to public/private key pairs.
CRYPT_CREATE_SALT	Typically, a number of extra bits are left over when a session key is created from a hash value. There are 88 bits left over when a 40-bit session key is created from a 128- bit hash value. If this flag is set, the key is assigned a salt value based on the unused hash value bits. This salt value can be retrieved by calling CPGetKeyParam with the dwParam parameter set to KP_SALT. If this flag is not set, the key is given a salt value of zero. When keys with nonzero salt values are exported using CPExportKey, the salt value must also be obtained and kept with the key BLOB.
CRYPT_NO_SALT	No salt value is allocated for a 40-bit symmetric key.
CRYPT_USER_ PROTECTED	The user is notified through a dialog box or another method when this key is used to attempt certain actions. The precise behavior is specified by the CSP being used. If the provider context is opened with the CRYPT_SILENT flag set, using this flag causes a failure with the last error set to NTE_SILENT_CONTEXT. Microsoft cryptographic providers support 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_UPDATE_KEY	Some CSPs use session keys derived from multiple hash values. When this is the case, CPDeriveKey must be called multiple times. If this flag is set, a new session key is not generated. Instead, the key specified by phKey is modified. The precise behavior of this flag is dependent on the type of key being generated and on the particular CSP being used. Microsoft cryptographic providers ignore this flag.
CRYPT_SERVER	This flag is used only with Schannel providers. If this flag is set, the key to be generated is a server-write key; otherwise, it is a client-write key.

phKey

Address to which the function copies the handle of 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

The CPDeriveKey function completes the hash of the hash object passed in as hBaseData. After CPDeriveKey has been called, no more data can be added to that hash object. Additional calls to CPHashData or CPHashSessionKey with that hash object fail. However, additional calls to CPDeriveKey, CPGetHashParam, CPSignHash, and CPVerifySignature use the completed hash object and succeed.

If CSP interoperability is important, session keys must be derived in the precise manner specified by the CSP's type. For information on how the key derivation must be performed, see Deriving Session Keys.

If interoperability is not a concern, a CSP is free to derive session keys in any manner.

For a description of the master hash object, see CPCreateHash.

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, CPGenKey, CryptDeriveKey