DXGKDDI_OPM_GET_RANDOM_NUMBER callback function (dispmprt.h)

Article
10/21/2021

The DxgkDdiOPMGetRandomNumber function retrieves the given protected output object's 128-bit cryptographically secure random number.

Syntax

DXGKDDI_OPM_GET_RANDOM_NUMBER DxgkddiOpmGetRandomNumber;

NTSTATUS DxgkddiOpmGetRandomNumber(
  [in]  PVOID MiniportDeviceContext,
  [in]  HANDLE ProtectedOutputHandle,
  [out] PDXGKMDT_OPM_RANDOM_NUMBER RandomNumber
)
{...}

Parameters

[in] MiniportDeviceContext

A handle to a context block associated with a display adapter. Previously, the display miniport driver's DxgkDdiAddDevice function provided this handle to the DirectX graphics kernel subsystem.

[in] ProtectedOutputHandle

The handle to a protected output object. The DxgkDdiOPMCreateProtectedOutput function creates the protected output object and returns the handle to the object.

[out] RandomNumber

A pointer to a DXGKMDT_OPM_RANDOM_NUMBER structure that receives the protected output object's 128-bit cryptographically secure random number if DxgkDdiOPMGetRandomNumber returns successfully.

If DxgkDdiOPMGetRandomNumber fails, the value that RandomNumber points to is unchanged.

Each protected output object must have a different 128-bit cryptographically secure random number associated with it.

Return value

DxgkDdiOPMGetRandomNumber returns STATUS_SUCCESS if it succeeds. Otherwise, it returns one of the error codes that are defined in Ntstatus.h.

Remarks

DxgkDdiOPMGetRandomNumber is called only once for each protected output and is never called after the call to the DxgkDdiOPMSetSigningKeyAndSequenceNumbers function occurs.

For more information about cryptographically secure random numbers, see section 2.8 in Applied Cryptography, Second Edition.

DxgkDdiOPMGetRandomNumber should be made pageable.

Requirements

Requirement	Value
Target Platform	Desktop
Header	dispmprt.h (include Dispmprt.h)
IRQL	PASSIVE_LEVEL (see Remarks section)