CryptDuplicateKey function (wincrypt.h)

Article
02/22/2024

Important This API is deprecated. New and existing software should start using Cryptography Next Generation APIs. Microsoft may remove this API in future releases.

The CryptDuplicateKey function makes an exact copy of a key and the state of the key.

Syntax

BOOL CryptDuplicateKey(
  [in]  HCRYPTKEY hKey,
  [in]  DWORD     *pdwReserved,
  [in]  DWORD     dwFlags,
  [out] HCRYPTKEY *phKey
);

Parameters

[in] hKey

A handle to the key to be duplicated.

[in] pdwReserved

Reserved for future use and must be NULL.

[in] dwFlags

Reserved for future use and must be zero.

[out] phKey

Address of the handle to the duplicated key. When you have finished using the key, release the handle by calling the CryptDestroyKey function.

Return value

If the function succeeds, the return value is nonzero (TRUE).

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

The error code prefaced by "NTE" is generated by the particular CSP being used. Some possible error codes are listed in the following table.

Return code	Description
ERROR_CALL_NOT_IMPLEMENTED	Because this is a new function, existing CSPs might not implement it. This error is returned if the CSP does not support this function.
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_KEY	A handle to the original key is not valid.

Remarks

CryptDuplicateKey makes a copy of a key and the exact state of the key. One scenario when this function can be used is when an application needs to encrypt two separate messages with the same key but with different salt values. The original key is generated and then a duplicate key is made by using the CryptDuplicateKey function. The different salt values are then set on the original and duplicate keys with separate calls to the CryptSetKeyParam function.

CryptDestroyKey must be called to destroy any keys that are created by using CryptDuplicateKey. Destroying the original key does not cause the duplicate key to be destroyed. After a duplicate key is made, it is separate from the original key. There is no shared state between the two keys.

Examples

The following example shows the creation of a session key that is a duplicate of an existing session key. For an example that includes the complete context for this example, see Example C Program: Duplicating a Session Key.

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

HCRYPTKEY    hDuplicateKey;

// Duplicate the key. hOriginalKey is a previously 
// assigned HCRYPTKEY variable.

if (CryptDuplicateKey(
     hOriginalKey, 
     NULL, 
     0, 
     &hDuplicateKey))
{
   printf("The session key has been duplicated. \n");
}
else
{
   printf("Error using CryptDuplicateKey.\n");
   exit(1);
}

// Insert code that uses the duplicate key here.

// When you have finished using the key, the handle must be released.

if (CryptDestroyKey(hDuplicateKey))
{
  printf("The handle has been released.\n");
}
else
{
  printf("The handle could not be released.\n");
}

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	wincrypt.h
Library	Advapi32.lib
DLL	Advapi32.dll