Função BCryptImportKey (bcrypt.h)

Artigo
07/16/2024

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

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 algoritmo 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 desembrulhar o BLOB de chave no parâmetro pbInput .

Observação 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 com 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	Importe uma chave simétrica de um BLOB de dados. O parâmetro pbInput é um ponteiro para uma estrutura de 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 a transferência interprocessa 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ó pode ser liberada depois que o phKey identificador de chave for destruído.

[in] cbKeyObject

O tamanho, em bytes, do buffer de 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 blob de chave que esse buffer contém.

[in] cbInput

O tamanho, em bytes, do buffer de de 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.

Valor de retorno

Retorna um código de 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 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 .

Observações

Dependendo de quais modos de processador um provedor dá suporte, BCryptImportKey podem ser chamados 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
de cliente com suporte mínimo	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	bcrypt.h
biblioteca	Bcrypt.lib
de DLL	Bcrypt.dll

Consulte também

BCryptDestroyKey

BCryptExportKey

BCryptImportKeyPair

Compartilhar via