Função CryptImportKey (wincrypt.h)
Sintaxe
BOOL CryptImportKey(
[in] HCRYPTPROV hProv,
[in] const BYTE *pbData,
[in] DWORD dwDataLen,
[in] HCRYPTKEY hPubKey,
[in] DWORD dwFlags,
[out] HCRYPTKEY *phKey
);
Parâmetros
[in] hProv
O identificador de um CSP obtido com a função CryptAcquireContext .
[in] pbData
Uma matriz BYTE que contém um cabeçalho BLOB PUBLICKEYSTRUC seguido pela chave criptografada. Esse BLOB de chave é criado pela função CryptExportKey , neste aplicativo ou por outro aplicativo possivelmente em execução em um computador diferente.
[in] dwDataLen
Contém o comprimento, em bytes, da chave BLOB.
[in] hPubKey
Um identificador para a chave criptográfica que descriptografa a chave armazenada em pbData. Essa chave deve vir do mesmo CSP ao qual hProv se refere. O significado desse parâmetro difere dependendo do tipo CSP e do tipo de chave BLOB que está sendo importado:
- Se o BLOB de chave for criptografado com o par de chaves de troca de chaves, por exemplo, um SIMPLEBLOB, esse parâmetro poderá ser o identificador para a chave de troca de chaves.
- Se o BLOB de chave for criptografado com uma chave de sessão, por exemplo, um PRIVATEKEYBLOB criptografado, esse parâmetro conterá o identificador dessa chave de sessão.
- Se o BLOB da chave não estiver criptografado, por exemplo, um PUBLICKEYBLOB, esse parâmetro não será usado e deverá ser zero.
- Se o BLOB de chave for criptografado com uma chave de sessão em um CSP Schannel , por exemplo, um OPAQUEKEYBLOB criptografado ou qualquer outro OPAQUEKEYBLOB específico do fornecedor, esse parâmetro não será usado e deverá ser definido como zero.
[in] dwFlags
Atualmente usado somente quando um par de chaves pública/privada na forma de um PRIVATEKEYBLOB é importado para o CSP.
Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
A chave que está sendo importada eventualmente será reexportada. Se esse sinalizador não for usado, as chamadas para CryptExportKey com o identificador de chave falharão. |
|
Esse sinalizador faz com que a formatação PKCS nº 1 versão 2 seja verificada com criptografia e descriptografia RSA ao importar SIMPLEBLOBs. |
|
Um valor sem sal é alocado para uma chave simétrica de 40 bits. Para obter mais informações, consulte Salt Value Functionality. |
|
Se esse sinalizador for definido, o CSP notificará o usuário por meio de uma caixa de diálogo ou de algum outro método quando determinadas ações forem tentadas usando essa chave. O comportamento preciso é especificado pelo CSP ou pelo tipo CSP usado. Se o contexto do provedor tiver sido adquirido com CRYPT_SILENT definido, o uso desse sinalizador causará uma falha e o último erro será definido como NTE_SILENT_CONTEXT. |
|
Permite a importação de uma chave RC2 maior que 16 bytes. Se esse sinalizador não estiver definido, as chamadas para a função CryptImportKey com chaves RC2 maiores que 16 bytes falharão e uma chamada para GetLastError retornará NTE_BAD_DATA. |
[out] phKey
Um ponteiro para um valor HCRYPTKEY que recebe o identificador da chave importada. Quando terminar de usar a chave, libere o identificador chamando a função CryptDestroyKey .
Retornar valor
Se a função for bem-sucedida, a função retornará diferente de zero.
Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.
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 seguem.
| Código de retorno | Descrição |
|---|---|
|
Alguns CSPs definem esse erro se uma chave privada for importada para um contêiner enquanto outro thread ou processo estiver usando essa chave. |
|
Um dos parâmetros especifica um identificador que não é válido. |
|
Um dos parâmetros contém um valor que não é válido. Geralmente, esse é um ponteiro que não é válido. |
|
O BLOB de chave simples a ser importado não é criptografado com o algoritmo de troca de chaves esperado. |
|
Não há suporte para o algoritmo que funciona com a chave pública a ser importada por esse CSP ou foi feita uma tentativa de importar uma chave de sessão criptografada com algo diferente de uma de suas chaves públicas. |
|
O parâmetro dwFlags especificado não é válido. |
|
O tipo de BLOB de chave não é compatível com esse CSP e, possivelmente, não é válido. |
|
O parâmetro hProv não contém um identificador de contexto válido. |
|
O número de versão do BLOB de chave não corresponde à versão do CSP. Isso geralmente indica que o CSP precisa ser atualizado. |
Comentários
Ao importar uma chave HMAC ( Código de Autenticação de Mensagem Baseado em Hash ), o chamador deve identificar a chave importada como um tipo PLAINTEXTKEYBLOB e definir o identificador de algoritmo apropriado no campo aiKeyAlg do cabeçalho BLOB PUBLICKEYSTRUC .
A função CryptImportKey pode ser usada para importar uma chave de texto não criptografado para algoritmos simétricos; no entanto, recomendamos que, para facilitar o uso, você use a função CryptGenKey . Quando você importa uma chave de texto não criptografado, a estrutura do BLOB de chave que é passada no parâmetro pbData é um PLAINTEXTKEYBLOB.
Você pode usar o tipo PLAINTEXTKEYBLOB com qualquer algoritmo ou tipo de combinação de teclas compatível com o CSP em uso.
Para obter um exemplo de importação de uma chave de texto não criptografado, consulte Exemplo de programa C: importando uma chave de texto sem formatação.
O exemplo a seguir mostra como você pode definir os campos de cabeçalho.
keyBlob.header.bType = PLAINTEXTKEYBLOB;
keyBlob.header.bVersion = CUR_BLOB_VERSION;
keyBlob.header.reserved = 0;
// CALG_AES_128 is used as an example. You would set this to the
// algorithm id that corresponds to the one used by the key.
keyBlob.header.aiKeyAlg = CALG_AES_128;
O comprimento da chave é especificado em keyBlob.keyLength, que é seguido pelos dados de chave reais.
Há suporte para os tamanhos de chave a seguir.
| Algoritmo | Tamanho da chave com suporte |
|---|---|
| CALG_DES | 64 bits |
| CALG_3DES_112 | 128 bits |
| CALG_3DES | 192 bits |
Exemplos
O exemplo a seguir mostra como importar uma chave de um BLOB de chave. Para obter um exemplo completo para essa função, consulte Exemplo de programa C: assinando um hash e verificando a assinatura de hash. Para obter código adicional que usa essa função, consulte Exemplo de programa C: descriptografando um arquivo.
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
BOOL ImportKey(HCRYPTPROV hProv, LPBYTE pbKeyBlob, DWORD dwBlobLen)
{
HCRYPTKEY hPubKey;
//---------------------------------------------------------------
// This code assumes that a cryptographic provider (hProv)
// has been acquired and that a key BLOB (pbKeyBlob) that is
// dwBlobLen bytes long has been acquired.
//---------------------------------------------------------------
// Get the public key of the user who created the digital
// signature and import it into the CSP by using CryptImportKey.
// The key to be imported is in the buffer pbKeyBlob that is
// dwBlobLen bytes long. This function returns a handle to the
// public key in hPubKey.
if(CryptImportKey(
hProv,
pbKeyBlob,
dwBlobLen,
0,
0,
&hPubKey))
{
printf("The key has been imported.\n");
}
else
{
printf("Public key import failed.\n");
return FALSE;
}
//---------------------------------------------------------------
// Insert code that uses the imported public key here.
//---------------------------------------------------------------
//---------------------------------------------------------------
// When you have finished using the key, you must release it.
if(CryptDestroyKey(hPubKey))
{
printf("The public key has been released.");
}
else
{
printf("The public key has not been released.");
return FALSE;
}
return TRUE;
}
Requisitos
| Requisito | Valor |
|---|---|
| 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 |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de