Platform SDK: Cryptography

CPHashSessionKey

The CPHashSessionKey function feeds a cryptographic key to a specified hash object. This allows a key to be hashed without the application having access to the key material.

BOOL CPHashSessionKey(
  HCRYPTPROV hProv,      // in
  HCRYPTHASH hHash,      // in
  HCRYPTKEY hKey,        // in
  DWORD dwFlags          // in
);

Parameters

hProv

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

hHash

Handle to a hash object. An application obtains this handle by using the CryptCreateHash function (in the CryptoAPI).

hKey

Handle to the session key object to be hashed.

dwFlags

The following dwFlags value is defined:

CRYPT_LITTLE_ENDIAN: Bytes of the key will be hashed in a little endian form. The Microsoft Cryptographic Providers support this flag in Microsoft Internet Explorer version 4.0 and later, Windows 98, and Windows 2000.

Note By default (dwFlags is 0) the bytes of the key are hashed in a big endian form.

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.

Error	Description
NTE_BAD_ALGID	The hHash handle specifies a hash algorithm that this function does not support.
NTE_BAD_FLAGS	The dwFlags parameter is non-zero.
NTE_BAD_HASH	The hash object specified by the hHash parameter is invalid.
NTE_BAD_ HASH_STATE	An attempt was made to add data to a hash object that is already marked as "finished."
NTE_BAD_KEY	A keyed hash algorithm is being used, but the session key is no longer valid. This error will be generated if the session key passed to CPCreateHash is destroyed before the hashing operating is complete.
NTE_BAD_UID	The CSP context that was specified when the hash object was created cannot now be found.
NTE_FAIL	The function failed in some unexpected way.

Remarks

The only data this function adds to the hash object is the session key material, itself. If necessary, an application, not the CSP, can hash the key's salt, initialization vector, and other hash state material. Depending on the CSP type, the key material might need to be formatted or padded in some specific way before being added to the hash. See CSP Interoperability for more details.

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.

CPHashSessionKey

Parameters

Return Values

Remarks

Requirements

See Also