Compartilhar via


Função BCryptGenRandom (bcrypt.h)

A função BCryptGenRandom gera um número aleatório.

Sintaxe

NTSTATUS BCryptGenRandom(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [in, out] PUCHAR            pbBuffer,
  [in]      ULONG             cbBuffer,
  [in]      ULONG             dwFlags
);

Parâmetros

[in, out] hAlgorithm

O identificador de um provedor de algoritmos criado usando a função BCryptOpenAlgorithmProvider. O algoritmo especificado quando o provedor foi criado deve dar suporte à interface do gerador de número aleatório.

[in, out] pbBuffer

O endereço de um buffer que recebe o número aleatório. O tamanho desse buffer é especificado pelo parâmetro cbBuffer.

[in] cbBuffer

O tamanho, em bytes, do buffer de pbBuffer.

[in] dwFlags

Um conjunto de sinalizadores que modificam o comportamento dessa função. Esse parâmetro pode ser zero ou o valor a seguir.

Valor Significado
BCRYPT_RNG_USE_ENTROPY_IN_BUFFER
0x00000001
Essa função usará o número no buffer pbBuffer como entropia adicional para o número aleatório. Se esse sinalizador não for especificado, essa função usará um número aleatório para a entropia.

Windows 8 e posteriores: Esse sinalizador é ignorado no Windows 8 e posterior.

BCRYPT_USE_SYSTEM_PREFERRED_RNG
0x00000002
Use o algoritmo de gerador de número aleatório preferido pelo sistema. O parâmetro hAlgorithm deve ser NULL.

BCRYPT_USE_SYSTEM_PREFERRED_RNG só tem suporte em PASSIVE_LEVELIRQL. Para obter mais informações, consulte Comentários.

Windows Vista: Este sinalizador não tem suporte sem SP2.

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 no parâmetro hAlgorithm não é válido.
STATUS_INVALID_PARAMETER
Um ou mais parâmetros não são válidos.

Observações

O provedor de número aleatório padrão implementa um algoritmo para gerar números aleatórios que estão em conformidade com o padrão NIST SP800-90, especificamente a parte CTR_DRBG desse padrão.

Windows Vista: Antes do Windows Vista com Service Pack 1 (SP1), o provedor de número aleatório padrão implementa um algoritmo para gerar números aleatórios que estejam em conformidade com o padrão FIPS 186-2.

Dependendo de quais modos de processador um provedor dá suporte, BCryptGenRandom 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 todos os ponteiros passados para a função BCryptGenRandom deverão se referir à memória nãopagada (ou bloqueada). Windows Vista: O provedor da Microsoft não dá suporte à chamada em DISPATCH_LEVEL.

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 ou Cng.lib(para modo Kernel)
de DLL Bcrypt.dll