Função BCryptGenerateKeyPair (bcrypt.h)

Artigo
07/16/2024

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

Manipulação de um provedor de algoritmo 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 4.096 bits e deve ser um múltiplo de 64.
BCRYPT_DSA_ALGORITHM	Antes do 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. A partir do Windows 8, o tamanho da chave deve ser maior ou igual a 512 bits, menor ou igual a 3.072 bits e deve ser um múltiplo de 64. O processamento de tamanhos de chave menores ou iguais a 1.024 bits adere ao FIPS 186-2. O processamento de tamanhos de chave maiores que 1024 e menores ou iguais a 3072 adere ao 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.

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

Observações

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 devem 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