Função BCryptGenerateSymmetricKey (bcrypt.h)

  • Artigo

A função BCryptGenerateSymmetricKey cria um objeto de 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ó poderá ser liberada depois que o identificador de chave phKey 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 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 alguns 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.

Nota É 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 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.

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.

Comentários

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ão paga (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