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 de 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 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 em Windows 8 e posteriores.
BCRYPT_USE_SYSTEM_PREFERRED_RNG 0x00000002	Use o algoritmo 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: Não há suporte para esse sinalizador sem SP2.

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

O provedor de números aleatórios 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 o Service Pack 1 (SP1), o provedor de números aleatórios padrão implementa um algoritmo para gerar números aleatórios que estão em conformidade com o padrão FIPS 186-2.

Dependendo de quais modos de processador um provedor dá suporte, BCryptGenRandom 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 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
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 ou Cng.lib(para o modo Kernel)
DLL	Bcrypt.dll