Função BCryptGenerateSymmetricKey (bcrypt.h)

Artigo
07/16/2024

A função BCryptGenerateSymmetricKey cria um objeto chave para uso com um algoritmo de criptografia de chave simétrica de uma chave fornecida.

Sintaxe

NTSTATUS BCryptGenerateSymmetricKey(
  [in, out]       BCRYPT_ALG_HANDLE hAlgorithm,
  [out]           BCRYPT_KEY_HANDLE *phKey,
  [out, optional] PUCHAR            pbKeyObject,
  [in]            ULONG             cbKeyObject,
  [in]            PUCHAR            pbSecret,
  [in]            ULONG             cbSecret,
  [in]            ULONG             dwFlags
);

Parâmetros

[in, out] hAlgorithm

O identificador de um provedor de algoritmos criado com a função BCryptOpenAlgorithmProvider. O algoritmo especificado quando o provedor foi criado deve dar suporte à criptografia de chave simétrica.

[out] phKey

Um ponteiro para um BCRYPT_KEY_HANDLE que recebe o identificador da chave. 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. 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.

Se o valor desse parâmetro for NULL e o valor do parâmetro cbKeyObject for zero, a memória do objeto de chave será alocada e liberada por essa função.Windows 7: Essa funcionalidade de gerenciamento de memória está disponível a partir do Windows 7.

[in] cbKeyObject

O tamanho, em bytes, do buffer de pbKeyObject .

Se o valor desse parâmetro for zero e o valor do parâmetro pbKeyObject for NULL, a memória do objeto de chave será alocada e liberada por essa função.Windows 7: Essa funcionalidade de gerenciamento de memória está disponível a partir do Windows 7.

[in] pbSecret

Ponteiro para um buffer que contém a chave da qual criar o objeto de chave. O parâmetro cbSecret contém o tamanho desse buffer. Normalmente, esse é um hash de uma senha ou outros dados reproduzíveis. Se os dados passados excederem o tamanho da chave de destino, os dados serão truncados e o excesso será ignorado.

Observação É altamente recomendável que os aplicativos passem o número exato de bytes exigidos pela chave de destino.

[in] cbSecret

O tamanho, em bytes, do buffer de pbSecret.

[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.

Observações

Dependendo de quais modos de processador um provedor dá suporte, BCryptGenerateSymmetricKey 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 BCryptGenerateSymmetricKey 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

Compartilhar via