WdfDeviceInitAssignSDDLString function

[Applies to KMDF only]

The WdfDeviceInitAssignSDDLString method assigns a security setting for a device.

Syntax

NTSTATUS WdfDeviceInitAssignSDDLString(
  PWDFDEVICE_INIT  DeviceInit,
  PCUNICODE_STRING SDDLString
);

Parameters

DeviceInit

A pointer to a WDFDEVICE_INIT structure.

SDDLString

A pointer to a UNICODE_STRING structure that describes a Unicode string. This string is an SDDL representation of a security descriptor.

Return Value

If the operation succeeds, WdfDeviceInitAssignSDDLString returns STATUS_SUCCESS. Additional return values include:

Return code Description
STATUS_INSUFFICIENT_RESOURCES
The system cannot allocate space to store the device name.

Remarks

Your driver can specify a security setting by using a subset of Security Descriptor Definition Language (SDDL). The Wdmsec.h file defines a set of SDDL_DEVOBJ_XXX-formatted constants that you can use. For more information about security descriptors and SDDL, see Securing Device Objects.

System administrators can override the specified security descriptor by adding a security descriptor to the registry. For more information, see IoCreateDeviceSecure.

Before calling WdfDeviceInitAssignSDDLString, your driver must call WdfDeviceInitAssignName, or it must call WdfDeviceInitSetCharacteristics and specify FILE_AUTOGENERATED_DEVICE_NAME, because you cannot provide a security descriptor for an unnamed device object.

If the driver calls WdfDeviceInitAssignSDDLString, it must do so before it calls WdfDeviceCreate. For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.

For more information about security issues, see Security Issues for Framework-Based Drivers.

  If you are writing a UMDF driver, you  must modify your driver's INF file to provide an appropriate security descriptor for the stack. For more information, see <a href="https://msdn.microsoft.com/library/windows/hardware/ff563688">Securing Device Objects</a>. For more information about using the registry, see <a href="https://msdn.microsoft.com/library/windows/hardware/ff563759">Setting Device Object Registry Properties During Installation</a>.

Examples

The following code example assigns a security setting for a device.

NTSTATUS status;

status = WdfDeviceInitAssignSDDLString(
                                       pDeviceInit,
                                       &SDDL_DEVOBJ_SYS_ALL_ADM_ALL
                                       );

Requirements

   
Target Platform Universal
Minimum KMDF version 1.0
Header wdfdevice.h (include Wdf.h)
Library Wdf01000.sys (see Framework Library Versioning.)
IRQL PASSIVE_LEVEL
DDI compliance rules ChildDeviceInitAPI, DeviceInitAPI, DriverCreate, InitFreeDeviceCallback, InitFreeDeviceCreate, InitFreeNull, KmdfIrql, KmdfIrql2, PdoDeviceInitAPI, PdoInitFreeDeviceCallback, PdoInitFreeDeviceCreate