This topic has not yet been rated - Rate this topic

CPHashSessionKey function

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.

Syntax

Copy

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

Parameters

hProv [in]

A handle to a particular key container within the cryptographic service provider (CSP). This handle is obtained by a call to the CPAcquireContext function.

hHash [in]

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

hKey [in]

A handle to the session key object to be hashed.

dwFlags [in]

The following dwFlags value is defined.

Value	Meaning
CRYPT_LITTLE_ENDIAN	Bytes of the key will be hashed in a little-endian form.

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

Return value

If the function succeeds, the function returns TRUE.

If the function fails, it returns FALSE, and the appropriate error code from the following table must be set using SetLastError.

Return code	Description
NTE_BAD_ALGID	The hHash handle specifies a hash algorithm that this function does not support.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero.
NTE_BAD_HASH	The hash object specified by the hHash parameter is not valid.
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 is generated when the session key passed to the CPCreateHash function is destroyed before the hashing operation 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 salt of the key, the 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. For more information, see CSP Interoperability.

Requirements