Função BCryptImportKey (bcrypt.h)

  • Artigo

A função BCryptImportKey importa uma chave simétrica de um BLOB de chave. A função BCryptImportKeyPair é usada para importar um par de chaves pública/privada.

Sintaxe

NTSTATUS BCryptImportKey(
  [in]            BCRYPT_ALG_HANDLE hAlgorithm,
  [in, optional]  BCRYPT_KEY_HANDLE hImportKey,
  [in]            LPCWSTR           pszBlobType,
  [out]           BCRYPT_KEY_HANDLE *phKey,
  [out, optional] PUCHAR            pbKeyObject,
  [in]            ULONG             cbKeyObject,
  [in]            PUCHAR            pbInput,
  [in]            ULONG             cbInput,
  [in]            ULONG             dwFlags
);

Parâmetros

[in] hAlgorithm

O identificador do provedor de algoritmos para importar a chave. Esse identificador é obtido chamando a função BCryptOpenAlgorithmProvider .

[in, optional] hImportKey

O identificador da chave de criptografia de chave necessária para desencapsular o BLOB de chave no parâmetro pbInput .

Nota O identificador deve ser fornecido pelo mesmo provedor que forneceu a chave que está sendo importada.

 

Windows Server 2008 e Windows Vista: Esse parâmetro não é usado e deve ser definido como NULL.

[in] pszBlobType

Uma cadeia de caracteres Unicode terminada em nulo que contém um identificador que especifica o tipo de BLOB contido no buffer pbInput . Esse pode ser um dos valores a seguir.

Valor Significado
BCRYPT_AES_WRAP_KEY_BLOB
 Importe uma chave simétrica de um BLOB de chave encapsulada por chave AES. O parâmetro hImportKey deve referenciar um ponteiro de BCRYPT_KEY_HANDLE válido para a chave de criptografia de chave.

Windows Server 2008 e Windows Vista: Não há suporte para esse tipo de BLOB.
BCRYPT_KEY_DATA_BLOB
 Importar uma chave simétrica de um BLOB de dados. O parâmetro pbInput é um ponteiro para uma estrutura BCRYPT_KEY_DATA_BLOB_HEADER imediatamente seguida pelo BLOB de chave.
BCRYPT_OPAQUE_KEY_BLOB
 Importe um BLOB de chave simétrica em um formato específico para um único CSP. BLOBs opacos não são transferíveis e devem ser importados usando o mesmo CSP que gerou o BLOB. BLOBs opacos destinam-se apenas a serem usados para transferência entre processos de chaves e não são adequados para serem persistidos e lidos entre versões de um provedor.

[out] phKey

Um ponteiro para um BCRYPT_KEY_HANDLE que recebe o identificador da chave importada. Esse identificador é usado em funções subsequentes que exigem uma chave, como BCryptEncrypt. Esse identificador deve ser liberado quando não for mais necessário passando-o para a função BCryptDestroyKey .

[out, optional] pbKeyObject

Um ponteiro para um buffer que recebe o objeto de chave importado. O parâmetro cbKeyObject contém o tamanho desse buffer. O tamanho necessário desse buffer pode ser obtido chamando a função BCryptGetProperty para obter a propriedade BCRYPT_OBJECT_LENGTH . Isso fornecerá o tamanho do objeto de chave para o algoritmo especificado.

Essa memória só poderá ser liberada depois que o identificador de chave phKey for destruído.

[in] cbKeyObject

O tamanho, em bytes, do buffer pbKeyObject .

[in] pbInput

O endereço de um buffer que contém o BLOB de chave a ser importado. O parâmetro cbInput contém o tamanho desse buffer. O parâmetro pszBlobType especifica o tipo de chave BLOB que esse buffer contém.

[in] cbInput

O tamanho, em bytes, do buffer pbInput .

[in] dwFlags

Um conjunto de sinalizadores que modificam o comportamento dessa função. Nenhum sinalizador está definido no momento, portanto, esse parâmetro deve ser zero.

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
STATUS_SUCCESS
 A função foi bem-sucedida.
STATUS_BUFFER_TOO_SMALL
 O tamanho do objeto de chave especificado pelo parâmetro cbKeyObject não é grande o suficiente para manter o objeto de chave.
STATUS_INVALID_HANDLE
 O identificador de algoritmo no parâmetro hAlgorithm não é válido.
STATUS_INVALID_PARAMETER
 Um ou mais dos parâmetros não são válidos.
STATUS_NOT_SUPPORTED
 O provedor de algoritmo especificado pelo parâmetro hAlgorithm não dá suporte ao tipo BLOB especificado pelo parâmetro pszBlobType .

Comentários

Dependendo de quais modos de processador um provedor dá suporte, BCryptImportKey pode ser chamado do modo de usuário ou do modo kernel. Os chamadores do modo kernel podem ser executados em PASSIVE_LEVELIRQL ou DISPATCH_LEVEL IRQL. Se o nível IRQL atual for DISPATCH_LEVEL, o identificador fornecido no parâmetro hAlgorithm deverá ter sido aberto usando o sinalizador BCRYPT_PROV_DISPATCH e quaisquer ponteiros passados para a função BCryptImportKey deverão se referir à memória nãopagada (ou bloqueada).

Para chamar essa função no modo kernel, use Cng.lib, que faz parte do DDK (Driver Development Kit). Windows Server 2008 e Windows Vista: Para chamar essa função no modo kernel, use Ksecdd.lib.

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 bcrypt.h
Biblioteca Bcrypt.lib
DLL Bcrypt.dll

Confira também

BCryptDestroyKey

BCryptExportKey

BCryptImportKeyPair