NCryptOpenKey, fonction (ncrypt.h)

La fonction NCryptOpenKey ouvre une clé qui existe dans le fournisseur de stockage de clé CNG spécifié.

Syntaxe

SECURITY_STATUS NCryptOpenKey(
  [in]  NCRYPT_PROV_HANDLE hProvider,
  [out] NCRYPT_KEY_HANDLE  *phKey,
  [in]  LPCWSTR            pszKeyName,
  [in]  DWORD              dwLegacyKeySpec,
  [in]  DWORD              dwFlags
);

Paramètres

[in] hProvider

Handle du fournisseur de stockage de clés à partir duquel ouvrir la clé.

[out] phKey

Pointeur vers une variable NCRYPT_KEY_HANDLE qui reçoit le handle de clé. Une fois que vous avez terminé d’utiliser ce handle, relâchez-le en le transmettant à la fonction NCryptFreeObject .

[in] pszKeyName

Pointeur vers une chaîne Unicode terminée par null qui contient le nom de la clé à récupérer.

[in] dwLegacyKeySpec

Identificateur hérité qui spécifie le type de clé. Il peut s’agir de l’une des valeurs suivantes.

Valeur	Signification
AT_KEYEXCHANGE	La clé est une clé d’échange de clé.
AT_SIGNATURE	La clé est une clé de signature.
0	La clé n’est pas des types ci-dessus.

[in] dwFlags

Indicateurs qui modifient le comportement de la fonction. Il peut s’agir de zéro ou d’une combinaison d’une ou plusieurs des valeurs suivantes.

Valeur	Signification
NCRYPT_MACHINE_KEY_FLAG	Ouvrez la clé de l’ordinateur local. Si cet indicateur n’est pas présent, la clé utilisateur actuelle est ouverte.
NCRYPT_SILENT_FLAG	Demande que le fournisseur de services de clé (KSP) n’affiche aucune interface utilisateur. Si le fournisseur doit afficher l’interface utilisateur pour fonctionner, l’appel échoue et le KSP doit définir le code d’erreur NTE_SILENT_CONTEXT comme dernière erreur.

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_BAD_KEYSET	La clé spécifiée est introuvable.
NTE_INVALID_HANDLE	Le paramètre hProvider 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

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 blocage peut se produire et le service peut cesser de répondre.

Pour des raisons de performances, les KSP basés sur les logiciels Microsoft mettez en cache des éléments de clé privée dans l’autorité de sécurité locale (LSA) tant qu’un handle de la clé est ouvert. La LSA est un processus système privilégié. Par conséquent, d’autres utilisateurs ne peuvent pas accéder à cette copie mise en cache de la clé, sauf si l’utilisateur dispose de privilèges d’administrateur sur le système. Ce comportement ne peut pas être modifié par le biais de la configuration.

Configuration requise

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