Función BCryptGenRandom (bcrypt.h)

  • Artículo

La función BCryptGenRandom genera un número aleatorio.

Sintaxis

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

Parámetros

[in, out] hAlgorithm

Identificador de un proveedor de algoritmos creado mediante la función BCryptOpenAlgorithmProvider . El algoritmo que se especificó cuando se creó el proveedor debe admitir la interfaz del generador de números aleatorios.

[in, out] pbBuffer

Dirección de un búfer que recibe el número aleatorio. El tamaño de este búfer se especifica mediante el parámetro cbBuffer .

[in] cbBuffer

Tamaño, en bytes, del búfer pbBuffer .

[in] dwFlags

Conjunto de marcas que modifican el comportamiento de esta función. Este parámetro puede ser cero o el valor siguiente.

Valor Significado
BCRYPT_RNG_USE_ENTROPY_IN_BUFFER
0x00000001
 Esta función usará el número en el búfer pbBuffer como entropía adicional para el número aleatorio. Si no se especifica esta marca, esta función usará un número aleatorio para la entropía.

Windows 8 y versiones posteriores: esta marca se omite en Windows 8 y versiones posteriores.
BCRYPT_USE_SYSTEM_PREFERRED_RNG
0x00000002
 Use el algoritmo de generador de números aleatorios preferido por el sistema. El parámetro hAlgorithm debe ser NULL.

BCRYPT_USE_SYSTEM_PREFERRED_RNG solo se admite en PASSIVE_LEVELIRQL. Para obtener más información, vea la sección Comentarios.

Windows Vista: Esta marca no se admite sin SP2.

Valor devuelto

Devuelve un código de estado que indica el éxito o error de la función.

Entre los posibles códigos de retorno se incluyen, entre otros, los siguientes.

Código devuelto Descripción
STATUS_SUCCESS
 La función se realizó correctamente.
STATUS_INVALID_HANDLE
 El identificador del parámetro hAlgorithm no es válido.
STATUS_INVALID_PARAMETER
 Uno o más parámetros no son válidos.

Comentarios

El proveedor de números aleatorios predeterminado implementa un algoritmo para generar números aleatorios que cumpla con el estándar NIST SP800-90, específicamente la parte CTR_DRBG de ese estándar.

Windows Vista: Antes de Windows Vista con Service Pack 1 (SP1), el proveedor de números aleatorios predeterminado implementa un algoritmo para generar números aleatorios que cumplan con el estándar FIPS 186-2.

En función de los modos de procesador que admita un proveedor, se puede llamar a BCryptGenRandom desde el modo de usuario o el modo kernel. Los autores de llamadas en modo kernel se pueden ejecutar en PASSIVE_LEVELIRQL o DISPATCH_LEVEL IRQL. Si el nivel irQL actual es DISPATCH_LEVEL, el identificador proporcionado en el parámetro hAlgorithm debe haberse abierto con la marca BCRYPT_PROV_DISPATCH y los punteros pasados a la función BCryptGenRandom deben hacer referencia a la memoria no paginada (o bloqueada). Windows Vista: El proveedor de Microsoft no admite llamadas en DISPATCH_LEVEL.

Para llamar a esta función en modo kernel, use Cng.lib, que forma parte del Kit de desarrollo de controladores (DDK). Windows Server 2008 y Windows Vista: Para llamar a esta función en modo kernel, use Ksecdd.lib.

Requisitos

Requisito Value
Cliente mínimo compatible Windows Vista [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado bcrypt.h
Library Bcrypt.lib o Cng.lib(Para el modo kernel)
Archivo DLL Bcrypt.dll