Device Naming Techniques for KMDF Drivers | Developing Drivers with the Windows Driver Foundation (Pro Developer)

KMDF device objects do not have fixed names. The framework sets FILE_AUTOGENERATED_DEVICE_NAME in the device's characteristics for PDOs, according to the WDM requirements.

The framework also supports the creation and registration of device interfaces on all Plug and Play devices and manages device interfaces for its drivers. Whenever possible, you should use device interfaces instead of the older fixed name/symbolic link techniques.

However, if legacy applications require that a device has a name, you can name the device and specify its security descriptor in security descriptor definition language (SDDL). The security descriptor controls which users can open the device.

By convention, a fixed device name is associated with a fixed symbolic link name, such as \DosDevices\MyDeviceName. The framework supports the creation and management of a symbolic link and automatically deletes the link when the device is destroyed. The framework also enables the creation of a symbolic link name for an unnamed Plug and Play device.

In addition to the guidelines in the WDK, you should follow these rules regarding naming device objects:

Name device objects only when necessary.
Provide security descriptors for device interfaces and for named device objects.

Named Device Objects

Even though applications open devices by name, FDOs and filter DOs usually do not have names. Instead of naming device objects, drivers define device interfaces though which applications can open the device. PDOs, however, must have names.

Tip See "Controlling Device Access in Framework-Based Drivers" in the WDK for naming exceptions-online at http://go.microsoft.com/fwlink/?LinkId=81579.

By default, when the framework creates the PDO, the Windows I/O manager assigns a system-generated name. You should override this default in your driver only if the driver supports old software, such as an application that expects a specific device name or if the driver stack includes old drivers that require such names. To override the default and assign a name to a device object, a driver calls WdfDeviceInitAssignName.

Every device object that has a name must also have a security descriptor. Windows uses the security descriptor to determine which users have permission to access the device and its device interfaces.

Symbolic link names are not the same as device object names. Symbolic link names are typically created by older drivers that run with applications that use MS-DOS device names to access a device. When a driver creates a symbolic link name for its device, the framework associates the link with the name that the Windows I/O manager assigned to the PDO. However, if the driver names the FDO, the framework associates the symbolic link with the FDO name.

Security Descriptors

A security descriptor defines who can access a particular resource, such as a device interface or device object. Security descriptors are expressed in SDDL. The Wdmsec.h header file in the WDK predefines a number of security descriptors that are useful for drivers.

Both the framework and Windows apply default security descriptors according to the following list:

Open table as spreadsheet

When the driver…	The security descriptor is…
Creates a device object	The default value applied by the Windows I/O manager: SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_R_RES_R.
Calls WdfDeviceInitAssignName	The default value applied by the framework: SDDL_DEVOBJ_SYS_ALL_ADM_ALL.
Calls WdfDeviceInitAssignSDDLString	The SDDL string supplied in the call.

The security descriptor for the device interface, by default, is the same as the security descriptor for the device's PDO. An INF file can override this default for a device or a device setup class.

Tip See "SDDL for Device Objects" in the WDK for information about security descriptors-online at http://go.microsoft.com/fwlink/?LinkId=80626. See also "Creating Secure Device Installations" in the WDK for details on creating security settings in driver INF files-online at http://go.microsoft.com/fwlink/?LinkId=80625.

Listing 6-7 shows how the Osrusbfx2 driver assigns an SDDL string to a raw PDO. This source code is from Osrusbfx2\Sys\Enumswitches\Rawpdo.c.

Listing 6-7: Assigning an SDDL string to a raw PDO

 NTSTATUS OsrEvtDeviceListCreatePdo(     WDFCHILDLIST DeviceList,     PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER           IdentificationDescription,     PWDFDEVICE_INIT ChildInit     ) {     NTSTATUS                        status;     WDFDEVICE                       hChild = NULL;     . . . // Additional declarations and code omitted.     // To create a RAW PDO, we must provide a class GUID.     status = WdfPdoInitAssignRawDevice (ChildInit,             &GUID_DEVCLASS_OSRUSBFX2);     if (!NT_SUCCESS(status)) {         goto Cleanup;     }     status = WdfDeviceInitAssignSDDLString (ChildInit,                &SDDL_DEVOBJ_SYS_ALL_ADM_ALL);     if (!NT_SUCCESS(status)) {         goto Cleanup;     }     // Perform additional initialization.     . . . // Code omitted for brevity.     // Create the PDO for the child device.     status = WdfDeviceCreate (&ChildInit, WDF_NO_OBJECT_ATTRIBUTES,                  &hChild);     if (!NT_SUCCESS(status)) {         goto Cleanup;     }     // Additional initialization and setup follows.     . . . // Code omitted for brevity. Cleanup:     return status; }

This function initializes device-specific information and creates a PDO for a child USB device. It assigns a security descriptor by calling WdfDeviceInitAssignSDDLString, passing a pointer to the WDFDEVICE_INIT structure and the SDDL_DEVOBJ_SYS_ALL_ADM_ALL security descriptor. Windows uses the security descriptor for the PDO to determine who has access rights to the device interfaces that are associated with the device. This descriptor allows any kernel-mode component and any application running with Administrator privilege to control the device. No other users can access the device.