Função NCryptEnumKeys (ncrypt.h)

  • Artigo

A função NCryptEnumKeys obtém os nomes das chaves armazenadas pelo provedor.

Sintaxe

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

O identificador do provedor de armazenamento de chaves para o qual enumerar as chaves. Esse identificador é obtido com a função NCryptOpenStorageProvider .

[in, optional] pszScope

Esse parâmetro não é usado no momento e deve ser NULL.

[out] ppKeyName

O endereço de um ponteiro para uma estrutura NCryptKeyName que recebe o nome da chave recuperada. Quando o aplicativo terminar de usar essa memória, libere-o chamando a função NCryptFreeBuffer .

[in, out] ppEnumState

O endereço de um ponteiro VOID que recebe informações de estado de enumeração usadas em chamadas subsequentes para essa função. Essas informações só têm significado para o provedor de armazenamento de chaves e são opacas para o chamador. O provedor de armazenamento de chaves usa essas informações para determinar qual item é o próximo na enumeração. Se a variável apontada por esse parâmetro contiver NULL, a enumeração será iniciada desde o início.

Quando essa memória não for mais necessária, ela deverá ser liberada passando esse ponteiro para a função NCryptFreeBuffer .

[in] dwFlags

Sinalizadores que modificam o comportamento da função. Isso pode ser zero ou uma combinação de um ou mais dos valores a seguir.

Valor Significado
NCRYPT_MACHINE_KEY_FLAG
 Enumerar as chaves para o computador local. Se esse sinalizador não estiver presente, as chaves de usuário atuais serão enumeradas.
NCRYPT_SILENT_FLAG
 Solicita que o KSP (provedor de serviços de chave) não exiba nenhuma interface do usuário. Se o provedor precisar exibir a interface do usuário para operar, a chamada falhará e o KSP deverá definir o código de erro NTE_SILENT_CONTEXT como o último erro.

Retornar valor

Retorna um código status que indica o êxito ou a falha da função.

Os códigos de retorno possíveis incluem, mas não se limitam a, o seguinte.

Código de retorno Descrição
ERROR_SUCCESS
 A função foi bem-sucedida.
NTE_BAD_FLAGS
 O parâmetro dwFlags contém um valor que não é válido.
NTE_INVALID_HANDLE
 O parâmetro hProvider não é válido.
NTE_INVALID_PARAMETER
 Um ou mais dos parâmetros não são válidos.
NTE_NO_MEMORY
 Ocorreu uma falha de alocação de memória.
NTE_NO_MORE_ITEMS
 O final da enumeração foi atingido.
NTE_SILENT_CONTEXT
 O parâmetro dwFlags contém o sinalizador NCRYPT_SILENT_FLAG , mas a chave que está sendo enumerada requer interação do usuário.

Comentários

Essa função recupera apenas um item cada vez que é chamada. O estado da enumeração é armazenado na variável apontada pelo parâmetro ppEnumState , portanto, isso deve ser preservado entre chamadas para essa função. Quando a última chave armazenada pelo provedor tiver sido recuperada, essa função retornará NTE_NO_MORE_ITEMS da próxima vez que for chamada. Para iniciar a enumeração, defina a variável apontada pelo parâmetro ppEnumState como NULL, libere a memória apontada pelo parâmetro ppKeyName , se não for NULL, e chame essa função novamente.

Um serviço não deve chamar essa função de sua Função StartService. Se um serviço chamar essa função de sua função StartService, um deadlock poderá ocorrer e o serviço poderá parar de responder.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho ncrypt.h
Biblioteca Ncrypt.lib
DLL Ncrypt.dll