Funzione NCryptTranslateHandle (ncrypt.h)

Articolo
03/05/2024

La funzione NCryptTranslateHandle converte un handle CryptoAPI in un handle di chiavi CNG.

Sintassi

SECURITY_STATUS NCryptTranslateHandle(
  [out, optional] NCRYPT_PROV_HANDLE *phProvider,
  [out]           NCRYPT_KEY_HANDLE  *phKey,
  [in]            HCRYPTPROV         hLegacyProv,
  [in, optional]  HCRYPTKEY          hLegacyKey,
  [in, optional]  DWORD              dwLegacyKeySpec,
  [in]            DWORD              dwFlags
);

Parametri

[out, optional] phProvider

Puntatore a una variabile NCRYPT_PROV_HANDLE che riceve l'handle del provider di archiviazione chiavi CNG che possiede la chiave CNG inserita nel parametro phKey . Questo parametro può essere NULL se questo handle non è necessario.

[out] phKey

Puntatore a una variabile NCRYPT_KEY_HANDLE che riceve l'handle della chiave CNG.

[in] hLegacyProv

Handle del provider CryptoAPI che contiene la chiave da tradurre. Questa funzione convertirà la chiave CryptoAPI che si trova nel contenitore in questo provider.

[in, optional] hLegacyKey

Handle di una chiave CryptoAPI da usare per determinare la specifica della chiave per la chiave restituita. Questo parametro viene ignorato se il parametro dwLegacyKeySpec contiene un valore diverso da zero.

Se hLegacyKey è NULL e dwLegacyKeySpec è zero, questa funzione tenterà di determinare la specifica della chiave dall'handle hLegacyProv .

[in, optional] dwLegacyKeySpec

Specifica la specifica della chiave per la chiave. Questo può essere uno dei valori seguenti.

Valore	Significato
0	La chiave è nessuna dei tipi seguenti.
AT_KEYEXCHANGE 1	La chiave è una chiave di scambio delle chiavi.
AT_SIGNATURE 2	La chiave è una chiave di firma.

Se hLegacyKey è NULL e dwLegacyKeySpec è zero, questa funzione tenterà di determinare la specifica della chiave dall'handle hLegacyProv .

[in] dwFlags

Set di flag che modificano il comportamento di questa funzione. Per questa funzione non sono definiti flag.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, ma non sono limitati a, i seguenti.

Codice restituito	Descrizione
ERROR_SUCCESS	La funzione ha avuto esito positivo.
NTE_BAD_FLAGS	Il parametro dwFlags contiene un valore non valido.
NTE_INVALID_PARAMETER	Uno o più parametri non sono validi.
NTE_NO_MEMORY	Si è verificato un errore di allocazione della memoria.

Commenti

Questa è una funzione helper destinata a aiutare le applicazioni e i componenti di sistema che attualmente usano CryptoAPI per eseguire una transizione graziosa all'uso di CNG.

Questa funzione avrà esito positivo solo se un provider di archiviazione chiavi CNG è registrato con un nome o un alias identico al nome del provider di servizi di crittografia (CSP) a cui fa riferimento il parametro hLegacyProv .

Questa funzione eseguirà i passaggi seguenti per tradurre l'handle CSP in un handle di chiave CNG:

Ottenere il nome del CSP dall'handle hLegacyProv .
Aprire il provider CNG il cui nome o alias è identico al nome CSP.
Ottenere il nome del contenitore di chiavi corrente nel CSP.
Ottenere la chiave CryptoAPI, convertirla in una chiave CNG e restituirla nel parametro phKey .

Un servizio non deve chiamare questa funzione dalla funzione StartService. Se un servizio chiama questa funzione dalla funzione StartService, può verificarsi un deadlock e il servizio potrebbe interrompere la risposta.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ncrypt.h
Libreria	Ncrypt.lib
DLL	Ncrypt.dll

Condividi tramite