SEEDER_ERROR WINAPI WS_get_seed( WIN32_SEEDER that, unsigned char *buffer, unsigned int *desired_length )Through this function system information can be collected from the computer. The first parameter represents the seeder instance which is to be used for the operation. The second parameter (buffer) has to point to a buffer into which the gathered system information will be written by Winseed. The third parameter (desired_length) has to point to an unsigned int which is used as an inout parameter. Before the function call this unsigned int has to be set to the size in bytes of the memory block to which the parameter buffer points, after the call it will contain the number of bytes actually written to the memory block. The number of bytes delivered can be smaller than the buffer size but will never be bigger.
The number of requested bytes, i.e. the buffer size, can be bigger than the internal seed size, but Winseed can not deliver more bytes than are contained in the internal seed. The number of requested bytes on the other hand can be (much) smaller than the internal seed size. In this case Winseed copies only the number of requested bytes from the internal seed into the output buffer. The following approach is taken to ensure that not too much entropy is lost even if the caller chooses to only retrieve a fraction of the collected data. After the gathering operation the full internal seed is hashed, using MD5, and the resulting hash value is XOR'ed on the first 16 bytes of the collected information. If therefore the original data contained at least 128 bits of entropy the first 16 bytes of the updated internal seed, i.e. the original seed plus the XOR'ed hash result, should also contain 128 bits of entropy. In other words if the caller retrieves at least 16 bytes of the updated internal seed it can be expected that the returned bytes contain as much entropy as the full size internal seed. This statement is of course only true under the assumption that the full length internal seed does not contain more entropy than 128 bits. If it does and you retrieve not the full length seed you loose a certain amount of entropy. This feature has been included for reasons of safety (safety in the sense that it makes it more difficult to use Winseed in a dangerous way) and does not constitute appropriate post processing as mentioned at Overview.
The WS_get_seed function checks all its parameters whether they are NULL pointers or not.
The implementation of WS_get_seed differs between the slow seeder and the fast seeder. The slow seeder dynamically allocates a buffer of the size WS_get_internal_seed_size before it starts the gathering operation and deallocates this buffer afterwards. The fast seeder on the other hand collects a fixed amount of data from the system and therefore makes use of a fixed length buffer. As a consequence the fast seeder ignores the current internal seed size. Due to this fact you never should get the error code PCP_SEEDER_TOO_SMALL from a fast seeder even if you set its internal seed size to 0.
Return values:
If the function call succeeds the value PCP_SUCCESS is returned. If the function call fails one of the error codes described at error reference is returned.