Share via

IOCTL_HAL_GET_HWENTROPY (Windows Embedded CE 6.0)

  • Article

1/5/2010

This IOCTL retrieves a 64-bit random number based upon an OEM-defined device hardware identifier.

The KernelIoControl function calls this IOCTL.

Parameters

  • dwIoControlCode
    [in] Set to IOCTL_HAL_GET_HWENTROPY.
  • lpInBuf
    [in] Set to NULL.
  • nInBufsize
    [in] Set to zero.

  • lpOutBuf
    [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.

  • nOutBufSize
    [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

If the function succeeds, the return value is TRUE. If the function fails, the return value is zero or FALSE.

If the return value is FALSE, GetLastError will be set to 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 is equal to ERROR_INVALID_PARAMETER, the parameters to the function were invalid.

If support is not provided for IOCTL_HAL_GET_HWENTROPY within the OEMIoControl function or if the request fails, the return value is FALSE.

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
Windows Embedded CE Windows CE .NET 4.1 and later

See Also

Reference

Device Information IOCTLs
OEMIoControl

Other Resources

KernelIoControl
GetLastError