Funzione CryptDuplicateKey (wincrypt.h)

Importante Questa API è deprecata. Il software nuovo e esistente deve iniziare a usare le API di nuova generazione di crittografia. Microsoft può rimuovere questa API nelle versioni future.

 

La funzione CryptDuplicateKey esegue una copia esatta di una chiave e lo stato della chiave.

Sintassi

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

Parametri

[in] hKey

Handle per la chiave da duplicare.

[in] pdwReserved

Riservato per l'uso futuro e deve essere NULL.

[in] dwFlags

Riservato per l'uso futuro e deve essere zero.

[out] phKey

Indirizzo dell'handle alla chiave duplicata. Al termine dell'uso della chiave, rilasciare l'handle chiamando la funzione CryptDestroyKey .

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).

Se la funzione ha esito negativo, il valore restituito è zero (FALSE). Per informazioni sull'errore estese, chiamare GetLastError.

Il codice di errore preceduto da "NTE" viene generato dal particolare CSP usato. Alcuni codici di errore possibili sono elencati nella tabella seguente.

Codice restituito	Descrizione
ERROR_CALL_NOT_IMPLEMENTED	Poiché si tratta di una nuova funzione, i provider di servizi di rete esistenti potrebbero non implementarlo. Questo errore viene restituito se il CSP non supporta questa funzione.
ERROR_INVALID_PARAMETER	Uno dei parametri contiene un valore non valido. Questo è più spesso un puntatore che non è valido.
NTE_BAD_KEY	Un handle per la chiave originale non è valido.

Commenti

CryptDuplicateKey esegue una copia di una chiave e lo stato esatto della chiave. Uno scenario quando questa funzione può essere usata è quando un'applicazione deve crittografare due messaggi separati con la stessa chiave ma con valori salt diversi. La chiave originale viene generata e quindi viene eseguita una chiave duplicata usando la funzione CryptDuplicateKey . I diversi valori salt vengono quindi impostati sulle chiavi originali e duplicate con chiamate separate alla funzione CryptSetKeyParam .

CryptDestroyKey deve essere chiamato per eliminare tutte le chiavi create usando CryptDuplicateKey. La eliminazione della chiave originale non causa l'eliminazione della chiave duplicata. Dopo aver eseguito una chiave duplicata, è separata dalla chiave originale. Non esiste uno stato condiviso tra le due chiavi.

Esempio

Nell'esempio seguente viene illustrata la creazione di una chiave di sessione duplicata di una chiave di sessione esistente. Per un esempio che include il contesto completo per questo esempio, vedere Esempio di programma C: duplicare una chiave di sessione.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h
Libreria	Advapi32.lib
DLL	Advapi32.dll

Vedi anche

CryptDestroyKey

CryptSetKeyParam

Generazione di chiavi e funzioni di Exchange