Función NCryptEnumKeys (ncrypt.h)

  • Artículo

La función NCryptEnumKeys obtiene los nombres de las claves almacenadas por el proveedor.

Sintaxis

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

Parámetros

[in] hProvider

Identificador del proveedor de almacenamiento de claves para el que se van a enumerar las claves. Este identificador se obtiene con la función NCryptOpenStorageProvider .

[in, optional] pszScope

Este parámetro no se usa actualmente y debe ser NULL.

[out] ppKeyName

Dirección de un puntero a una estructura NCryptKeyName que recibe el nombre de la clave recuperada. Cuando la aplicación haya terminado de usar esta memoria, liberela llamando a la función NCryptFreeBuffer .

[in, out] ppEnumState

Dirección de un puntero VOID que recibe información de estado de enumeración que se usa en llamadas posteriores a esta función. Esta información solo tiene significado para el proveedor de almacenamiento de claves y es opaco para el autor de la llamada. El proveedor de almacenamiento de claves usa esta información para determinar qué elemento se encuentra a continuación en la enumeración. Si la variable a la que apunta este parámetro contiene NULL, la enumeración se inicia desde el principio.

Cuando esta memoria ya no es necesaria, debe liberarse pasando este puntero a la función NCryptFreeBuffer .

[in] dwFlags

Marcas que modifican el comportamiento de la función. Puede ser cero o una combinación de uno o varios de los valores siguientes.

Valor Significado
NCRYPT_MACHINE_KEY_FLAG
 Enumere las claves del equipo local. Si esta marca no está presente, se enumeran las claves de usuario actuales.
NCRYPT_SILENT_FLAG
 Solicita que el proveedor de servicios clave (KSP) no muestre ninguna interfaz de usuario. Si el proveedor debe mostrar la interfaz de usuario para funcionar, se produce un error en la llamada y el KSP debe establecer el código de error NTE_SILENT_CONTEXT como último error.

Valor devuelto

Devuelve un código de estado que indica el éxito o error de la función.

Entre los posibles códigos de retorno se incluyen, entre otros, los siguientes.

Código devuelto Descripción
ERROR_SUCCESS
 La función se realizó correctamente.
NTE_BAD_FLAGS
 El parámetro dwFlags contiene un valor que no es válido.
NTE_INVALID_HANDLE
 El parámetro hProvider no es válido.
NTE_INVALID_PARAMETER
 Uno o más parámetros no son válidos.
NTE_NO_MEMORY
 Error de asignación de memoria.
NTE_NO_MORE_ITEMS
 Se ha alcanzado el final de la enumeración.
NTE_SILENT_CONTEXT
 El parámetro dwFlags contiene la marca NCRYPT_SILENT_FLAG , pero la clave que se enumera requiere interacción del usuario.

Comentarios

Esta función recupera solo un elemento cada vez que se llama. El estado de la enumeración se almacena en la variable a la que apunta el parámetro ppEnumState , por lo que debe conservarse entre las llamadas a esta función. Cuando se haya recuperado la última clave almacenada por el proveedor, esta función devolverá NTE_NO_MORE_ITEMS la próxima vez que se llame. Para iniciar la enumeración, establezca la variable a la que apunta el parámetro ppEnumState en NULL, libere la memoria a la que apunta el parámetro ppKeyName , si no es NULL, y vuelva a llamar a esta función.

Un servicio no debe llamar a esta función desde su función StartService. Si un servicio llama a esta función desde su función StartService, se puede producir un interbloqueo y el servicio puede dejar de responder.

Requisitos

Requisito Value
Cliente mínimo compatible Windows Vista [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado ncrypt.h
Library Ncrypt.lib
Archivo DLL Ncrypt.dll