Função CryptDestroyKey (wincrypt.h)

Artigo
08/27/2023

Importante Essa API foi preterida. O software novo e existente deve começar a usar APIs de Criptografia de Próxima Geração. A Microsoft pode remover essa API em versões futuras.

A função CryptDestroyKey libera o identificador referenciado pelo parâmetro hKey . Depois que um identificador de chave for liberado, ele não será mais válido e não poderá ser usado novamente.

Se o identificador se referir a uma chave de sessão ou a uma chave pública que foi importada para o provedor de serviços criptográficos (CSP) por meio de CryptImportKey, essa função destruirá a chave e liberará a memória usada pela chave. Muitos CSPs substituem a memória em que a chave foi mantida antes de liberá-la. No entanto, o par de chaves pública/privada subjacente não é destruído por essa função. Somente o identificador é destruído.

Sintaxe

BOOL CryptDestroyKey(
  [in] HCRYPTKEY hKey
);

Parâmetros

[in] hKey

O identificador da chave a ser destruída.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Os códigos de erro precedidos por "NTE" são gerados pelo CSP específico que está sendo usado. Alguns códigos de erro possíveis são listados na tabela a seguir.

Código de retorno	Descrição
ERROR_BUSY	O objeto de chave especificado por hKey está sendo usado no momento e não pode ser destruído.
ERROR_INVALID_HANDLE	O parâmetro hKey especifica um identificador que não é válido.
ERROR_INVALID_PARAMETER	O parâmetro hKey contém um valor que não é válido.
NTE_BAD_KEY	O parâmetro hKey não contém um identificador válido para uma chave.
NTE_BAD_UID	O contexto CSP especificado quando a chave foi criada não pode ser encontrado.

Comentários

As chaves ocuparão o espaço de memória do sistema operacional e o espaço de memória do CSP. Alguns CSPs são implementados em hardware com recursos de memória limitados. Os aplicativos devem destruir todas as chaves com a função CryptDestroyKey quando terminarem com elas.

Todos os identificadores de chave que foram criados ou importados usando um CSP específico devem ser destruídos antes que o identificador CSP seja liberado com a função CryptReleaseContext .

Exemplos

Para obter um exemplo que usa a função CryptDestroyKey , consulte Exemplo de Programa C: Criando e hash de uma chave de sessão.

Requisitos


Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wincrypt.h
Biblioteca	Advapi32.lib
DLL	Advapi32.dll