Fonction NCryptEnumKeys (ncrypt.h)

Article
02/29/2024

La fonction NCryptEnumKeys obtient les noms des clés stockées par le fournisseur.

Syntaxe

SECURITY_STATUS NCryptEnumKeys(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] LPCWSTR            pszScope,
  [out]          NCryptKeyName      **ppKeyName,
  [in, out]      PVOID              *ppEnumState,
  [in]           DWORD              dwFlags
);

Paramètres

[in] hProvider

Handle du fournisseur de stockage de clés pour lequel énumérer les clés. Ce handle est obtenu avec la fonction NCryptOpenStorageProvider .

[in, optional] pszScope

Ce paramètre n’est actuellement pas utilisé et doit avoir la valeur NULL.

[out] ppKeyName

Adresse d’un pointeur vers une structure NCryptKeyName qui reçoit le nom de la clé récupérée. Lorsque l’application a terminé d’utiliser cette mémoire, libérez-la en appelant la fonction NCryptFreeBuffer .

[in, out] ppEnumState

Adresse d’un pointeur VOID qui reçoit des informations d’état d’énumération utilisées dans les appels suivants à cette fonction. Ces informations ont une signification uniquement pour le fournisseur de stockage de clé et sont opaques pour l’appelant. Le fournisseur de stockage de clés utilise ces informations pour déterminer l’élément suivant de l’énumération. Si la variable pointée vers ce paramètre contient NULL, l’énumération est démarrée à partir du début.

Lorsque cette mémoire n’est plus nécessaire, elle doit être libérée en passant ce pointeur vers la fonction NCryptFreeBuffer .

[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	Énumérez les clés de l’ordinateur local. Si cet indicateur n’est pas présent, les clés utilisateur actuelles sont énumérées.
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_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.
NTE_NO_MORE_ITEMS	La fin de l’énumération a été atteinte.
NTE_SILENT_CONTEXT	Le paramètre dwFlags contient l’indicateur NCRYPT_SILENT_FLAG , mais la clé énumérée nécessite une interaction utilisateur.

Remarques

Cette fonction ne récupère qu’un seul élément chaque fois qu’il est appelé. L’état de l’énumération étant stocké dans la variable pointée vers le paramètre ppEnumState , il doit être conservé entre les appels à cette fonction. Lorsque la dernière clé stockée par le fournisseur a été récupérée, cette fonction retourne NTE_NO_MORE_ITEMS la prochaine fois qu’elle est appelée. Pour recommencer l’énumération, définissez la variable pointée vers le paramètre ppEnumState sur NULL, libérez la mémoire pointée par le paramètre ppKeyName , s’il n’est pas NULL, puis appelez à nouveau cette fonction.

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.

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

Partager via