Função NCryptOpenKey (ncrypt.h)

  • Artigo

A função NCryptOpenKey abre uma chave que existe no provedor de armazenamento de chaves CNG especificado.

Sintaxe

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

Parâmetros

[in] hProvider

O identificador do provedor de armazenamento de chaves do qual abrir a chave.

[out] phKey

Um ponteiro para uma variável NCRYPT_KEY_HANDLE que recebe o identificador de chave. Quando terminar de usar esse identificador, solte-o passando-o para a função NCryptFreeObject .

[in] pszKeyName

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que contém o nome da chave a ser recuperada.

[in] dwLegacyKeySpec

Um identificador herdado que especifica o tipo de chave. Esse pode ser um dos valores a seguir.

Valor Significado
AT_KEYEXCHANGE
 A chave é uma chave de troca de chaves.
AT_SIGNATURE
 A chave é uma chave de assinatura.
0
 A chave não é nenhum dos tipos acima.

[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
 Abra a chave para o computador local. Se esse sinalizador não estiver presente, a chave de usuário atual será aberta.
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_BAD_KEYSET
 A chave especificada não foi encontrada.
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.

Comentários

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.

Por motivos de desempenho, os KSPs baseados em software da Microsoft armazenam material de chave privada em cache na LSA (Autoridade de Segurança Local) desde que um identificador para a chave esteja aberto. O LSA é um processo de sistema privilegiado. Portanto, outros usuários não podem acessar essa cópia armazenada em cache da chave, a menos que o usuário possua privilégios de administrador no sistema. Esse comportamento não pode ser alterado por meio da configuração.

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