Função BCryptGenerateKeyPair (bcrypt.h)

  • Artigo

A função BCryptGenerateKeyPair cria um par de chaves pública/privada vazia. Depois de criar uma chave usando essa função, você pode usar a função BCryptSetProperty para definir suas propriedades; no entanto, a chave não pode ser usada até que a função BCryptFinalizeKeyPair seja chamada.

Sintaxe

NTSTATUS BCryptGenerateKeyPair(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [out]     BCRYPT_KEY_HANDLE *phKey,
  [in]      ULONG             dwLength,
  [in]      ULONG             dwFlags
);

Parâmetros

[in, out] hAlgorithm

Identificador de um provedor de algoritmos que dá suporte à assinatura, criptografia assimétrica ou contrato de chave. Esse identificador deve ter sido criado usando a função BCryptOpenAlgorithmProvider .

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

[in] dwLength

O comprimento, em bits, da chave. Os provedores de algoritmo têm restrições de tamanho de chave diferentes para cada algoritmo assimétrico padrão.

Identificador de algoritmo Significado
BCRYPT_DH_ALGORITHM
 O tamanho da chave deve ser maior ou igual a 512 bits, menor ou igual a 4096 bits e deve ser um múltiplo de 64.
BCRYPT_DSA_ALGORITHM
 Antes de Windows 8, o tamanho da chave deve ser maior ou igual a 512 bits, menor ou igual a 1024 bits e deve ser um múltiplo de 64.

Começando com Windows 8, o tamanho da chave deve ser maior ou igual a 512 bits, menor ou igual a 3072 bits e deve ser um múltiplo de 64. O processamento de tamanhos de chave menores ou iguais a 1024 bits segue o FIPS 186-2. O processamento de tamanhos de chave maiores que 1024 e menores ou iguais a 3072 segue o FIPS 186-3.
BCRYPT_ECDH_P256_ALGORITHM
 O tamanho da chave deve ser de 256 bits.
BCRYPT_ECDH_P384_ALGORITHM
 O tamanho da chave deve ser de 384 bits.
BCRYPT_ECDH_P521_ALGORITHM
 O tamanho da chave deve ser de 521 bits.
BCRYPT_ECDSA_P256_ALGORITHM
 O tamanho da chave deve ser de 256 bits.
BCRYPT_ECDSA_P384_ALGORITHM
 O tamanho da chave deve ser de 384 bits.
BCRYPT_ECDSA_P521_ALGORITHM
 O tamanho da chave deve ser de 521 bits.
BCRYPT_RSA_ALGORITHM
 O tamanho da chave deve ser maior ou igual a 512 bits, menor ou igual a 16384 bits e deve ser um múltiplo de 64.

[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_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 especificado não dá suporte à criptografia de chave assimétrica.

Comentários

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