WdfDeviceInitAssignSDDLString function (wdfdevice.h)

Artikel
04/18/2022

[Applies to KMDF only]

The WdfDeviceInitAssignSDDLString method assigns a security setting for a device.

Syntax

NTSTATUS WdfDeviceInitAssignSDDLString(
  [in]           PWDFDEVICE_INIT  DeviceInit,
  [in, optional] PCUNICODE_STRING SDDLString
);

Parameters

[in] DeviceInit

A pointer to a WDFDEVICE_INIT structure.

[in, optional] 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 Securing Device Objects. For more information about using the registry, see Setting Device Object Registry Properties During Installation.

Examples

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

NTSTATUS status;

status = WdfDeviceInitAssignSDDLString(
                                       pDeviceInit,
                                       &SDDL_DEVOBJ_SYS_ALL_ADM_ALL
                                       );

Requirements

Requirement	Value
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(kmdf), DeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCallback(kmdf), PdoInitFreeDeviceCreate(kmdf)

Delen via