CryptDuplicateHash function (wincrypt.h)

The CryptDuplicateHash function makes an exact copy of a hash to the point when the duplication is done. The duplicate hash includes the state of the hash.

A hash can be created in a piece-by-piece way. The CryptDuplicateHash function can be used to create separate hashes of two different contents that begin with the same content.

Syntax

BOOL CryptDuplicateHash(
  [in]  HCRYPTHASH hHash,
  [in]  DWORD      *pdwReserved,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

Parameters

[in] hHash

Handle of the hash to be duplicated.

[in] pdwReserved

Reserved for future use and must be zero.

[in] dwFlags

Reserved for future use and must be zero.

[out] phHash

Address of the handle of the duplicated hash. When you have finished using the hash, release the handle by calling the CryptDestroyHash function.

Return value

If the function succeeds, the function returns TRUE.

If the function fails, it returns FALSE. For extended error information, call GetLastError.

The error code prefaced by "NTE" is generated by the particular cryptographic service provider (CSP) that you are using. Some possible error codes follow.

Remarks

CryptDuplicateHash makes a copy of a hash and the exact state of the hash. This function might be used if a calling application needed to generate two hashes but both hashes had to start with some common data hashed. For example, a hash might be created, the common data hashed, a duplicate made with the CryptDuplicateHash function, and then the data unique to each hash would be added.

The CryptDestroyHash function must be called to destroy any hashes that are created with CryptDuplicateHash. Destroying the original hash does not cause the duplicate hash to be destroyed. After a duplicate hash is made, it is separate from the original hash. There is no shared state between the two hashes.

Examples

The following example shows making an exact copy of a hash. For an example that includes the complete context for this example, see Example C Program: Duplicating a Hash.

//-------------------------------------------------------------------
//  Declare and initialize variables.

HCRYPTPROV   hCryptProv = NULL;
HCRYPTHASH   hOriginalHash = NULL;
HCRYPTHASH   hDuplicateHash = NULL;

//-------------------------------------------------------------------
// Acquire a CSP context.

if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext succeeded. \n");
}
else
{
    printf("Error during CryptAcquireContext.\n");
    exit(1);
}
//-------------------------------------------------------------------
// Create a hash.

if (CryptCreateHash(
    hCryptProv, 
    CALG_SHA1, 
    0, 
    0,
    &hOriginalHash))
{
   printf("An empty hash object has been created. \n");
}
else
{
   printf("Error during CryptCreateHash.\n");
   exit(1);
}
//-------------------------------------------------------------------
// Hash a BYTE string.

if (CryptHashData(
    hOriginalHash, 
    (BYTE*)"Some Common Data", 
    sizeof("Some Common Data"), 0))
{
   printf("An original hash has been created. \n");
}
else
{
   printf("Error during CryptHashData.\n");
   exit(1);
}
//-------------------------------------------------------------------
// Duplicate the hash.

if (CryptDuplicateHash(
   hOriginalHash, 
   NULL, 
   0, 
   &hDuplicateHash))
{
   printf("The hash has been duplicated. \n");
}
else
{
   printf("Error during CryptDuplicateHash.\n");
   exit(1);
}
//-------------------------------------------------------------------
// At this point, the two hash objects are exactly the same.
// The two hash objects can be handled separately.
// When all processing on the hash object is completed, 
// both objects should be destroyed, and the cryptographic
// context should be released.

//-------------------------------------------------------------------
// Destroy the original hash.

if(CryptDestroyHash(hOriginalHash))
{
   printf("The original hash has been destroyed. \n");
}
else
{
   printf("Error during CryptDestroyHash on the original "
       "hash object.\n");
   exit(1);
}
//-------------------------------------------------------------------
// Destroy the duplicate hash.

if (CryptDestroyHash(hDuplicateHash))
{
   printf("The duplicate hash has been destroyed. \n");
}
else
{
   printf("Error during CryptDestroyHash on the duplicated hash object.\n");
   exit(1);
}

//-------------------------------------------------------------------
// Release the CSP.

if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

Requirements

See also

CryptDestroyHash

Hash and Digital Signature Functions