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 生成。 下表列出了一些可能的错误代码。

返回代码 说明
ERROR_CALL_NOT_IMPLEMENTED
 由于这是一个新函数，因此现有 CSP 可能无法实现它。 如果 CSP 不支持此函数，则返回此错误。
ERROR_INVALID_PARAMETER
 其中一个参数包含无效的值。 这通常是无效的指针。
NTE_BAD_KEY
 原始密钥的句柄无效。

注解

CryptDuplicateKey 会复制密钥和密钥的确切 状态 。 可以使用此函数的一种情况是，应用程序需要使用相同密钥但使用不同的 盐值加密两个单独的消息。 生成原始密钥，然后使用 CryptDuplicateKey 函数创建重复密钥。 然后，通过对 CryptSetKeyParam 函数的单独调用，在原始键和重复键上设置不同的 salt 值。

必须调用 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
Library Advapi32.lib
DLL Advapi32.dll

另请参阅

CryptDestroyKey

CryptSetKeyParam

密钥生成和交换函数