Função CryptImportKey (wincrypt.h)

Artigo
07/16/2024

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

A função CryptImportKey transfere um de chave criptográfica de uma de BLOB de chave para um de provedor de serviços criptográficos (CSP) . Essa função pode ser usada para importar uma chave de sessãoSchannel, chave de sessão regular de chave pública ou par de chaves pública/privada. Para todos, exceto a chave pública, a chave ou o par de chaves é criptografado.

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 PUBLICKEYSTRUC BLOB 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, do BLOB de chave.

[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 blob de chave que está sendo importado:

Se o BLOB de chave for criptografado com a chave par de chaves de troca, por exemplo, um SIMPLEBLOB, esse parâmetro poderá ser o identificador da chave de troca de chaves.
Se o BLOB de chave for criptografado com uma chave de sessão, por exemplo, umPRIVATEKEYBLOB criptografado, esse parâmetro conterá o identificador dessa chave de sessão.
Se o BLOB de 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 de Schannel, por exemplo, um OPAQUEKEYBLOB criptografado ou qualquer outro OPACOKEYBLOB específico do fornecedor, esse parâmetro não será usado e deverá ser definido como zero.

Observação alguns CSPs podem modificar esse parâmetro como resultado da operação. Os aplicativos que posteriormente usam essa chave para outras finalidades devem chamar a função CryptDuplicateKey para criar um identificador de chave duplicado. Quando o aplicativo terminar de usar o identificador, libere-o chamando a função CryptDestroyKey.

[in] dwFlags

Atualmente usado somente quando um par de chaves público/privado na forma de um PRIVATEKEYBLOB é importado para o CSP.

Esse parâmetro pode ser um dos valores a seguir.

Valor	Significado
CRYPT_EXPORTABLE	A chave que está sendo importada eventualmente deve ser reexportada. Se esse sinalizador não for usado, as chamadas para CryptExportKey com o identificador de chave falharão.
CRYPT_OAEP	Esse sinalizador faz com que a formatação PKCS nº 1 versão 2 seja verificada com criptografia RSA e descriptografia ao importar s SIMPLEBLOB.
CRYPT_NO_SALT	Um valor sem sal é alocado para uma chave simétrica de 40 bits. Para obter mais informações, consulte de funcionalidade de valor de sal.
CRYPT_USER_PROTECTED	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 foi adquirido com CRYPT_SILENT definido, usar esse sinalizador causará uma falha e o último erro será definido como NTE_SILENT_CONTEXT.
CRYPT_IPSEC_HMAC_KEY	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 HCRYPTKEY valor que recebe o identificador da chave importada. Quando terminar de usar a chave, libere o identificador chamando a função CryptDestroyKey.

Valor de retorno

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
ERROR_BUSY	Alguns CSPs definem esse erro se uma chave privada for importada para um contêiner enquanto outro thread ou processo estiver usando essa chave.
ERROR_INVALID_HANDLE	Um dos parâmetros especifica um identificador que não é válido.
ERROR_INVALID_PARAMETER	Um dos parâmetros contém um valor que não é válido. Isso geralmente é um ponteiro que não é válido.
NTE_BAD_ALGID	O de BLOB de chave simples a ser importado não é criptografado com o algoritmo de troca de chaves esperado.
NTE_BAD_DATA	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.
NTE_BAD_FLAGS	O parâmetro dwFlags especificado não é válido.
NTE_BAD_TYPE	O tipo de BLOB de chave não é compatível com esse CSP e possivelmente não é válido.
NTE_BAD_UID	O parâmetro hProv não contém um identificador de contexto válido.
NTE_BAD_VER	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.

Observações

Ao importar uma chave HMAC (Hash-Based Message Authentication Code), o chamador deve identificar a chave importada como um tipo de PLAINTEXTKEYBLOB e definir o identificador de algoritmo apropriado no campo aiKeyAlg do cabeçalho PUBLICKEYSTRUC BLOB.

A função CryptImportKey pode ser usada para importar uma chave de texto sem formatação para algoritmos simétricos; no entanto, recomendamos que, para facilitar o uso, você use a função CryptGenKey em vez disso. Quando você importa uma chave de texto sem formatação, 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 chaves compatível com o CSP em uso.

Para obter um exemplo de importação de uma chave de texto sem formatação, 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.

Observação os algoritmos HMAC não têm seus próprios identificadores de algoritmo; em vez disso, use CALG_RC2. CRYPT_IPSEC_HMAC_KEY permite a importação de chaves RC2 com mais de 16 bytes.

Para qualquer uma das permutações de chave DeS (Data Encryption Standard) que usam PLAINTEXTKEYBLOB, somente o tamanho da chave completa, incluindo o bit de paridade, pode ser importado.

Há suporte para os seguintes tamanhos de chave.

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
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	wincrypt.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Consulte também

CryptAcquireContext

CryptDestroyKey

CryptExportKey

geração de chaves e funções do Exchange

Compartilhar via