Expand Minimize

CryptHashSessionKey function

The CryptHashSessionKey function computes the cryptographic hash of a session key object. This function can be called multiple times with the same hash handle to compute the hash of multiple keys. Calls to CryptHashSessionKey can be interspersed with calls to CryptHashData.

Before calling this function, CryptCreateHash must be called to create the handle of a hash object.

Syntax


BOOL WINAPI CryptHashSessionKey(
  _In_  HCRYPTHASH hHash,
  _In_  HCRYPTKEY hKey,
  _In_  DWORD dwFlags
);

Parameters

hHash [in]

A handle to the hash object.

hKey [in]

A handle to the key object to be hashed.

dwFlags [in]

The following flag value is defined.

ValueMeaning
CRYPT_LITTLE_ENDIAN
0x00000001

When this flag is set, the bytes of the key are hashed in little-endian form. Note that by default (when dwFlags is zero), the bytes of the key are hashed in big-endian form.

 

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. For extended error information, call GetLastError.

The error codes prefaced by "NTE" are generated by the particular CSP you are using. Some possible error codes follow.

Return codeDescription
ERROR_INVALID_HANDLE

One of the parameters specifies a handle that is not valid.

ERROR_INVALID_PARAMETER

One of the parameters contains a value that is not valid. This is most often a pointer that is not valid.

NTE_BAD_ALGID

The hHash handle specifies an algorithm that this CSP 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 "finished."

NTE_BAD_KEY

A keyed hash algorithm is being used, but the session key is no longer valid. This error is generated if the session key is destroyed before the hashing operation is complete.

NTE_BAD_UID

The CSP context that was specified when the hash object was created cannot be found.

NTE_FAIL

The function failed in some unexpected way.

 

Examples

The following example shows computing the cryptographic hash of a session key object.


//--------------------------------------------------------------------
//  This code assumes that a cryptographic context handle has been 
//  acquired, that a hash object handle (hHash) has been
//  created, and that a session key handle (hKey) has been 
//  created.
//--------------------------------------------------------------------
// Compute the cryptographic hash on the key object.

if(CryptHashSessionKey(
   hHash, 
   hKey, 
   0))
{
    printf("The session key has been hashed. \n");
}
else
{
    printf("Error during CryptHashSessionKey!\n");
    exit(1);
}

// Use the hash of the key object. For instance, additional 
// data could be hashed and sent in a message to several recipients. 
// The recipients will be able to verify the message originator 
// if the session key used is also exported to them.

//--------------------------------------------------------------------
// Clean up. Destroy the hash object and the session key.

if(hHash) 
   CryptDestroyHash(hHash);
if(hKey) 
   CryptDestroyKey(hKey);

For an example that includes the complete context for this example, see Example C Program: Creating and Hashing a Session Key.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Hash and Digital Signature Functions
CryptCreateHash
CryptGenKey
CryptHashData

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.