Función CryptGenRandom (wincrypt.h)

  • Artículo
Importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API cryptography Next Generation. Microsoft puede quitar esta API en futuras versiones.
 
La función CryptGenRandom rellena un búfer con bytes criptográficos aleatorios.

Sintaxis

BOOL CryptGenRandom(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwLen,
  [in, out] BYTE       *pbBuffer
);

Parámetros

[in] hProv

Identificador de un proveedor de servicios criptográficos (CSP) creado por una llamada a CryptAcquireContext.

[in] dwLen

Número de bytes de datos aleatorios que se van a generar.

[in, out] pbBuffer

Búfer para recibir los datos devueltos. Este búfer debe tener al menos bytes dwLen de longitud.

Opcionalmente, la aplicación puede rellenar este búfer con datos para usarlos como inicialización aleatoria auxiliar.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).

Si se produce un error en la función, el valor devuelto es cero (FALSE). Para obtener información de error extendida, llame a GetLastError.

Los códigos de error precedidos por "NTE" se generan mediante el CSP en particular que se usa. Algunos códigos de error posibles se enumeran en la tabla siguiente.

Código devuelto Descripción
ERROR_INVALID_HANDLE
 Uno de los parámetros especifica un identificador que no es válido.
ERROR_INVALID_PARAMETER
 Uno de los parámetros contiene un valor que no es válido. Suele ser un puntero que no es válido.
NTE_BAD_UID
 El parámetro hProv no contiene un identificador de contexto válido.
NTE_FAIL
 Error en la función de alguna manera inesperada.

Comentarios

Los datos generados por esta función son criptográficamente aleatorios. Es mucho más aleatorio que los datos generados por el generador de números aleatorios típico, como el que se incluye con el compilador de C.

Esta función se usa a menudo para generar vectores de inicialización aleatorios y valores de sal.

Los generadores de números aleatorios de software funcionan fundamentalmente de la misma manera. Comienzan con un número aleatorio, conocido como inicialización, y luego usan un algoritmo para generar una secuencia pseudoaleatoriedad de bits basada en él. La parte más difícil de este proceso es obtener una inicialización que es verdaderamente aleatoria. Normalmente, esto se basa en la latencia de entrada del usuario o en la vibración de uno o varios componentes de hardware.

Con los CSP de Microsoft, CryptGenRandom usa el mismo generador de números aleatorios que usan otros componentes de seguridad. Esto permite que numerosos procesos contribuyan a una inicialización en todo el sistema. CryptoAPI almacena una inicialización aleatoria intermedia con cada usuario. Para formar el valor de inicialización para el generador de números aleatorios, una aplicación que realiza la llamada proporciona bits que puede tener (por ejemplo, entrada de control de tiempo del mouse o teclado) que se combinan con la inicialización almacenada y varios datos del sistema y datos de usuario, como el identificador de proceso y el identificador de subproceso, el reloj del sistema, la hora del sistema, el contador del sistema, estado de memoria, clústeres de disco libre, bloque de entorno de usuario con hash. Este resultado se usa para inicializar el generador de números pseudoaleatorios (PRNG). En Windows Vista con Service Pack 1 (SP1) y versiones posteriores, se usa una implementación del PRNG basado en modo contador AES especificado en la publicación especial de NIST 800-90. En Windows Vista, Windows Storage Server 2003 y Windows XP, se usa el PRNG especificado en Federal Information Processing Standard (FIPS) 186-2. Si una aplicación tiene acceso a un buen origen aleatorio, puede rellenar el búfer pbBuffer con algunos datos aleatorios antes de llamar a CryptGenRandom. A continuación, el CSP usa estos datos para aleatorizar aún más su inicialización interna. Es aceptable omitir el paso de inicializar el búfer pbBuffer antes de llamar a CryptGenRandom.

Ejemplos

En el ejemplo siguiente se muestra la generación de 8 bytes aleatorios. Se pueden usar para crear claves criptográficas o para cualquier aplicación que use números aleatorios. Para obtener un ejemplo que incluya el contexto completo de este ejemplo, vea Ejemplo C Program: Duplicación de una clave de sesión.

//--------------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV   hCryptProv;
BYTE         pbData[16];

//--------------------------------------------------------------------
//  This code assumes that a cryptographic context has been acquired 
//  For code details, see "Example C Program: Duplicating a Session 
//  Key."

//--------------------------------------------------------------------
// Generate a random initialization vector.

if(CryptGenRandom(
   hCryptProv, 
   8, 
   pbData)) 
{
     printf("Random sequence generated. \n");
}
else
{
     printf("Error during CryptGenRandom.\n");
     exit(1);
}

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado wincrypt.h
Library Advapi32.lib
Archivo DLL Advapi32.dll

Consulte también

CryptAcquireContext

CryptGenKey

CryptSetKeyParam

Generación de claves y funciones de Exchange