Função CryptDuplicateKey (wincrypt.h)

Importante Essa API foi preterida. O software novo e existente deve começar a usar APIs de Próxima Geração de Criptografia. A Microsoft pode remover essa API em versões futuras.

 

A função CryptDuplicateKey faz uma cópia exata de uma chave e o estado da chave.

Sintaxe

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

Parâmetros

[in] hKey

Um identificador para a chave a ser duplicada.

[in] pdwReserved

Reservado para uso futuro e deve ser NULL.

[in] dwFlags

Reservado para uso futuro e deve ser zero.

[out] phKey

Endereço do identificador para a chave duplicada. Quando terminar de usar a chave, libere o identificador chamando a função CryptDestroyKey .

Retornar valor

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError.

O código de erro precedido por "NTE" é gerado pelo CSP específico que está sendo usado. Alguns códigos de erro possíveis estão listados na tabela a seguir.

Código de retorno	Descrição
ERROR_CALL_NOT_IMPLEMENTED	Como essa é uma nova função, os CSPs existentes podem não implementá-la. Esse erro será retornado se o CSP não der suporte a essa função.
ERROR_INVALID_PARAMETER	Um dos parâmetros contém um valor que não é válido. Geralmente, esse é um ponteiro que não é válido.
NTE_BAD_KEY	Um identificador para a chave original não é válido.

Comentários

CryptDuplicateKey faz uma cópia de uma chave e o estado exato da chave. Um cenário em que essa função pode ser usada é quando um aplicativo precisa criptografar duas mensagens separadas com a mesma chave, mas com valores de sal diferentes. A chave original é gerada e, em seguida, uma chave duplicada é feita usando a função CryptDuplicateKey . Os diferentes valores de sal são definidos nas chaves originais e duplicadas com chamadas separadas para a função CryptSetKeyParam .

CryptDestroyKey deve ser chamado para destruir todas as chaves criadas usando CryptDuplicateKey. Destruir a chave original não faz com que a chave duplicada seja destruída. Depois que uma chave duplicada é feita, ela é separada da chave original. Não há nenhum estado compartilhado entre as duas chaves.

Exemplos

O exemplo a seguir mostra a criação de uma chave de sessão que é uma duplicata de uma chave de sessão existente. Para obter um exemplo que inclui o contexto completo para este exemplo, consulte Exemplo de programa C: duplicando uma chave de sessão.

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Advapi32.lib
DLL	Advapi32.dll

Confira também

Cryptdestroykey

Cryptsetkeyparam

Geração de chaves e funções do Exchange