Função NCryptTranslateHandle (ncrypt.h)

  • Artigo

A função NCryptTranslateHandle converte um identificador CryptoAPI em um identificador de chave CNG.

Sintaxe

SECURITY_STATUS NCryptTranslateHandle(
  [out, optional] NCRYPT_PROV_HANDLE *phProvider,
  [out]           NCRYPT_KEY_HANDLE  *phKey,
  [in]            HCRYPTPROV         hLegacyProv,
  [in, optional]  HCRYPTKEY          hLegacyKey,
  [in, optional]  DWORD              dwLegacyKeySpec,
  [in]            DWORD              dwFlags
);

Parâmetros

[out, optional] phProvider

Um ponteiro para uma variável NCRYPT_PROV_HANDLE que recebe o identificador do provedor de armazenamento de chaves CNG que possui a chave CNG colocada no parâmetro phKey . Esse parâmetro poderá ser NULL se esse identificador não for necessário.

[out] phKey

Um ponteiro para uma variável NCRYPT_KEY_HANDLE que recebe o identificador de chave CNG.

[in] hLegacyProv

O identificador do provedor CryptoAPI que contém a chave a ser convertida. Essa função traduzirá a chave CryptoAPI que está no contêiner neste provedor.

[in, optional] hLegacyKey

O identificador de uma chave CryptoAPI a ser usada para ajudar a determinar a especificação de chave para a chave retornada. Esse parâmetro será ignorado se o parâmetro dwLegacyKeySpec contiver um valor diferente de zero.

Se hLegacyKey for NULL e dwLegacyKeySpec for zero, essa função tentará determinar a especificação de chave do identificador hLegacyProv .

[in, optional] dwLegacyKeySpec

Especifica a especificação de chave para a chave. Esse pode ser um dos valores a seguir.

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

Se hLegacyKey for NULL e dwLegacyKeySpec for zero, essa função tentará determinar a especificação de chave do identificador hLegacyProv .

[in] dwFlags

Um conjunto de sinalizadores que modificam o comportamento dessa função. Nenhum sinalizador é definido para essa função.

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_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

Essa é uma função auxiliar destinada a ajudar aplicativos e componentes do sistema que atualmente usam a CryptoAPI para fazer uma transição normal para o uso do CNG.

Essa função só será bem-sucedida se um provedor de armazenamento de chaves CNG for registrado com um nome ou alias idêntico ao nome do provedor de serviços criptográficos (CSP) referenciado pelo parâmetro hLegacyProv .

Essa função executará as seguintes etapas para converter o identificador CSP em um identificador de chave CNG:

  1. Obtenha o nome do CSP do identificador hLegacyProv .
  2. Abra o provedor CNG cujo nome ou alias é idêntico ao nome do CSP.
  3. Obtenha o nome do contêiner de chave atual no CSP.
  4. Obtenha a chave CryptoAPI, converta-a em uma chave CNG e retorne-a no parâmetro phKey .
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 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho ncrypt.h
Biblioteca Ncrypt.lib
DLL Ncrypt.dll