NCryptTranslateHandle, fonction (ncrypt.h)

Article
03/06/2024

La fonction NCryptTranslateHandle traduit un handle CryptoAPI en handle de clé CNG.

Syntaxe

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
);

Paramètres

[out, optional] phProvider

Pointeur vers une variable NCRYPT_PROV_HANDLE qui reçoit le handle du fournisseur de stockage de clés CNG qui possède la clé CNG placée dans le paramètre phKey . Ce paramètre peut être NULL si ce handle n’est pas nécessaire.

[out] phKey

Pointeur vers une variable NCRYPT_KEY_HANDLE qui reçoit le handle de clé CNG.

[in] hLegacyProv

Handle du fournisseur CryptoAPI qui contient la clé à traduire. Cette fonction traduit la clé CryptoAPI qui se trouve dans le conteneur de ce fournisseur.

[in, optional] hLegacyKey

Handle d’une clé CryptoAPI à utiliser pour déterminer la spécification de la clé retournée. Ce paramètre est ignoré si le paramètre dwLegacyKeySpec contient une valeur autre que zéro.

Si hLegacyKey a la valeur NULL et dwLegacyKeySpec est égal à zéro, cette fonction tente de déterminer la spécification de clé à partir du handle hLegacyProv .

[in, optional] dwLegacyKeySpec

Spécifie la spécification de la clé. Il peut s’agir de l’une des valeurs suivantes.

Valeur	Signification
0	La clé ne correspond à aucun des types ci-dessous.
AT_KEYEXCHANGE 1	La clé est une clé d’échange de clé.
AT_SIGNATURE 2	La clé est une clé de signature.

Si hLegacyKey a la valeur NULL et dwLegacyKeySpec est égal à zéro, cette fonction tente de déterminer la spécification de clé à partir du handle hLegacyProv .

[in] dwFlags

Ensemble d’indicateurs qui modifient le comportement de cette fonction. Aucun indicateur n’est défini pour cette fonction.

Valeur retournée

Retourne un code status qui indique la réussite ou l’échec de la fonction.

Les codes de retour possibles incluent, sans s’y limiter, les éléments suivants.

Code de retour	Description
ERROR_SUCCESS	La fonction a réussi.
NTE_BAD_FLAGS	Le paramètre dwFlags contient une valeur qui n’est pas valide.
NTE_INVALID_PARAMETER	Un ou plusieurs paramètres ne sont pas valides.
NTE_NO_MEMORY	Un échec d’allocation de mémoire s’est produit.

Remarques

Il s’agit d’une fonction d’assistance destinée à aider les applications et les composants système qui utilisent actuellement CryptoAPI à effectuer une transition appropriée vers l’utilisation de CNG.

Cette fonction réussit uniquement si un fournisseur de stockage de clés CNG est inscrit avec un nom ou un alias identique au nom du fournisseur de services de chiffrement (CSP) auquel le paramètre hLegacyProv fait référence.

Cette fonction effectue les étapes suivantes pour traduire le handle CSP en handle de clé CNG :

Obtenez le nom du fournisseur de solutions Cloud à partir du handle hLegacyProv .
Ouvrez le fournisseur CNG dont le nom ou l’alias est identique au nom csp.
Obtenez le nom du conteneur de clé actuel dans le csp.
Obtenez la clé CryptoAPI, convertissez-la en clé CNG et retournez-la dans le paramètre phKey .

Un service ne doit pas appeler cette fonction à partir de sa fonction StartService. Si un service appelle cette fonction à partir de sa fonction StartService, un interblocage peut se produire et le service peut cesser de répondre.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ncrypt.h
Bibliothèque	Ncrypt.lib
DLL	Ncrypt.dll

Partager via