IOCTL_HAL_GET_HWENTROPY (Compact 2013)
10/16/2014
This I/O control message obtains a 64-bit random number based upon an OEM-defined device hardware identifier. Send this message with KernelIoControl.
Syntax
BOOL KernelIoControl(
DWORD dwIoControlCode, // use IOCTL_HAL_GET_HWENTROPY
LPVOID lpInBuffer, // pointer to input buffer
DWORD nInBufferSize, // input buffer size
LPVOID lpOutBuffer, // pointer to output buffer
DWORD nOutBufferSize, // output buffer size
LPDWORD lpBytesReturned // number of bytes returned
);
Parameters
- dwIoControlCode
[in] Control code for the operation. Use IOCTL_HAL_GET_HWENTROPY for this operation.
- lpInBuffer
Not used; set to NULL.
- nInBufferSize
[in] Set to zero.
- lpOutBuffer
[in, out] On input, set to the address of an allocated buffer to contain the 64-bit random seed. On output, the buffer is filled with the 64-bit random number.
- nOutBufferSize
[in] Set to the size of the buffer allocated to store the random number.
- lpBytesReturned
[in, out] On input, address of a DWORD that receives the size, in bytes, of the data returned. On output, set to the number of bytes written to the supplied buffer.
Return Values
Returns TRUE if successful; otherwise, returns FALSE. If support is not provided for IOCTL_HAL_GET_HWENTROPY within the OEMIoControl function, the return value is FALSE.
If the return value is FALSE, the GetLastError function returns the error encountered when processing the request. If GetLastError is equal to ERROR_NOT_SUPPORTED, IOCTL_HAL_GET_HWENTROPY is not supported on the device. If GetLastError is equal to ERROR_INSUFFICENT_BUFFER, the buffer passed into the KernelIoControl function was not large enough. In this case, if lpBytesReturned is not equal to NULL, the size of the required buffer is written to the location pointed to by this parameter. If GetLastError returns ERROR_INVALID_PARAMETER, the parameters to the function were invalid.
Remarks
OEMs must implement the section of code in the OAL to handle the call to the KernelIoControl function. The retrieved 64-bit random number should be the same across all calls on the same device. It should be different on each device. And it should not be possible to guess the number given the IOCTL_HAL_GET_HWENTROPY values for other devices.
Requirements
Header |
pkfuncs.h |