CryptDuplicateKey 函式 (wincrypt.h)

重要 此 API 已被取代。 新的和現有的軟體應該開始使用 密碼編譯新一代 API。 Microsoft 可能會在未來的版本中移除此 API。

 

CryptDuplicateKey 函式會製作密鑰和密鑰狀態的確切複本。

語法

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

參數

[in] hKey

要複製之索引鍵的句柄。

[in] pdwReserved

保留供日後使用，且必須是 NULL。

[in] dwFlags

保留供日後使用，且必須為零。

[out] phKey

重複索引鍵句柄的位址。 當您完成使用密鑰時，請呼叫 CryptDestroyKey 函式來釋放句柄。

傳回值

如果函式成功，則傳回值為非零 (TRUE) 。

如果函式失敗，則傳回值為零， (FALSE) 。 如需擴充錯誤資訊，請呼叫 GetLastError。

由 「NTE」 開頭的錯誤碼是由所使用的特定 CSP 所產生。 下表列出一些可能的錯誤碼。

傳回碼	Description
ERROR_CALL_NOT_IMPLEMENTED	因為這是新的函式，所以現有的 CSP 可能不會實作它。 如果 CSP 不支援此函式，就會傳回此錯誤。
ERROR_INVALID_PARAMETER	其中一個參數包含無效的值。 這通常是無效的指標。
NTE_BAD_KEY	原始索引鍵的句柄無效。

備註

CryptDuplicateKey 會複製密鑰和金鑰的確切 狀態 。 使用此函式的其中一個案例是應用程式需要使用相同的密鑰加密兩個不同的訊息，但具有不同的 salt 值。 會產生原始密鑰，然後使用 CryptDuplicateKey 函式建立重複的索引鍵。 然後，在原始和重複的索引鍵上設定不同的 salt 值，並以 對 CryptSetKeyParam 函式的個別呼叫。

必須呼叫 CryptDestroyKey，以終結使用 CryptDuplicateKey 建立的任何密鑰。 終結原始索引鍵並不會造成重複的索引鍵被終結。 建立重複的索引鍵之後，它會與原始索引鍵分開。 兩個金鑰之間沒有共享狀態。

範例

下列範例顯示建立會話密鑰，此金鑰是現有會話密鑰的複本。 如需包含此範例完整內容的範例，請參閱 範例 C 程式：複製會話密鑰。

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

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Advapi32.lib
Dll	Advapi32.dll

另請參閱

CryptDestroyKey

CryptSetKeyParam

金鑰產生和 Exchange 函式