The CPGenRandom function fills a buffer with random bytes.

Syntax

BOOL CPGenRandom(
  __in     HCRYPTPROV hProv,
  __in     DWORD dwLen,
  __inout  BYTE *pbBuffer
);

Parameters

hProv [in]

A handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext.

dwLen [in]

Number of bytes of random data to be generated.

pbBuffer [in, out]

Buffer to which the function copies the random data. This buffer is dwLen bytes in length.

Upon input to the function, this buffer can contain up to dwLen bytes of random data that the CSP can use to generate a seed value. This is discussed further in Remarks.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.

Remarks

CPGenRandom is one of the more difficult functions to implement correctly, and it must be done correctly to maintain the security of a CSP. CPGenRandom is used internally by the CPGenKey function, as well by applications when generating data items used in cryptographic protocols such as challenge strings. A CSP is not producing message security if values of the cryptographic keys or challenge strings produced by a CSP are predictable.

There are two components to a good random number generator: a method of getting a random seed, and an algorithm that will generate a good pseudo-random stream of data based on that seed.

Generating a random seed can depend on the hardware used by the CSP. If the CSP has access to a hardware random number source, the problem is solved. A completely software-based CSP might use one of the following sources:

• The system time.
• Any high-precision clocks that exist on the system board and peripherals.
• The cursor or mouse pointer location.
• Any accumulated physical state information devices such as in keyboard input buffers, I/O service queues, and video drivers.
• The number of tasks in the operating system scheduling queue, their task identifiers, or their code base addresses and sizes.
• Data from the application, passed into the CryptGenRandom function and passed on to CPGenRandom as the input bytes in pbBuffer.

Some or all of this data can be hashed along with the random seed from the previous session to create a random seed. New seeds should be generated periodically throughout the session, to avoid placing too much reliance on the pseudo-random stream generator.

After the random seed has been obtained, any number of algorithms can be used to generate a pseudo-random stream of data. Sometimes a stream cipher such as RC4 is used for this purpose, with the seed forming the keying material. The following sources describe other algorithms and techniques:

• Bellare, M., and P. Rogaway. Optimal Asymmetric Encryption. Advances in Cryptology—EUROCRYPT '94, ed. by A. deSantis, Springer-Verlag, 1995, pp. 92–111, Lecture Notes in Computer Science, vol. 950.
• Blum, L. , M. Blum, and M. Shub. A Simple Unpredictable Pseudo-Random Number Generator. SIAM Journal on Computing 15(2)(May 1986); 364–383.
• M. Blum and S. Micali, "How to generate cryptographically strong sequences of pseudo-random bits," SIAM Journal on Computing 13(4)(November 1984); 850–864.

The required header file, Cspdk.h, is available only by downloading the Cryptographic Service Provider Developer's Kit (CSPDK). It can be downloaded from the Microsoft Download Center.

Requirements

See Also

CryptGenRandom

Send comments about this topic to Microsoft

Build date: 11/16/2009