nf-wincrypt-cryptduplicatekey.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:wincrypt.CryptDuplicateKey	CryptDuplicateKey function (wincrypt.h)	Makes an exact copy of a key and the state of the key.	CryptDuplicateKey CryptDuplicateKey function [Security] _crypto2_cryptduplicatekey security.cryptduplicatekey wincrypt/CryptDuplicateKey	security\cryptduplicatekey.htm	security	c5658008-7c92-4877-871a-a764884efd79	12/05/2018	CryptDuplicateKey, CryptDuplicateKey function [Security], _crypto2_cryptduplicatekey, security.cryptduplicatekey, wincrypt/CryptDuplicateKey	wincrypt.h		Windows	Windows XP [desktop apps only]	Windows Server 2003 [desktop apps only]										Advapi32.lib	Advapi32.dll		Windows			19H1	CryptDuplicateKey wincrypt/CryptDuplicateKey	c++	APIRef kbSyntax	DllExport	Advapi32.dll API-MS-Win-Security-cryptoapi-l1-1-0.dll cryptsp.dll	CryptDuplicateKey

CryptDuplicateKey function

-description

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.

-parameters

-param hKey [in]

A handle to the key to be duplicated.

-param pdwReserved [in]

Reserved for future use and must be NULL.

-param dwFlags [in]

Reserved for future use and must be zero.

-param phKey [out]

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

-returns

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");
}

-see-also

CryptDestroyKey

CryptSetKeyParam

Key Generation and Exchange Functions