Manages and keeps track of active USB devices. More...

#include <DeviceManager.hpp>

Public Types
enum	EventType { EventType::Present = 0, EventType::Insert = 1, EventType::Update = 2, EventType::Remove = 3 }
	Type of event that took place on the device. More...

enum	AuthorizedDefaultType { AuthorizedDefaultType::Keep = -128, AuthorizedDefaultType::Wired = -1, AuthorizedDefaultType::None = 0, AuthorizedDefaultType::All = 1, AuthorizedDefaultType::Internal = 2 }
	Defines which devices are authorized by default. More...

Public Member Functions
	DeviceManager (DeviceManagerHooks &hooks)
	Constructs new device manager object with given hooks. More...

	DeviceManager (const DeviceManager &rhs)
	Constructs new device manager from a given device manager. More...

const DeviceManager &	operator= (const DeviceManager &rhs)
	Constructs new device manager based on given device manager and assignes it to this. More...

virtual	~DeviceManager ()
	Default destructor.

virtual void	setEnumerationOnlyMode (bool state)=0
	When a device is inserted into a system it's authorized default will stay unchanged. More...

virtual void	start ()=0
	Starts the deamon for monitoring USB device events.

virtual void	stop ()=0
	Stops the daemon that is monitoring USB device events.

virtual void	scan ()=0
	Scans the system for USB devices.

virtual void	scan (const std::string &devpath)=0
	Scan for USB devices on given path. More...

void	setAuthorizedDefault (AuthorizedDefaultType authorized)
	Enables you to set the default authorization of USB devices. More...

AuthorizedDefaultType	getAuthorizedDefault () const
	Returns current authorized default setting. More...

void	setRestoreControllerDeviceState (bool enabled)
	Controls whether USBGuard daemon tries to restore the device attribute values to the state before modification on shutdown. More...

bool	getRestoreControllerDeviceState () const
	Returns true if restore controller device state is enabled, false otherwise. More...

virtual std::shared_ptr< Device >	applyDevicePolicy (uint32_t id, Rule::Target target)=0
	Applies given policy to device with given ID. More...

virtual void	insertDevice (std::shared_ptr< Device > device)
	Adds new device into a device map. More...

std::shared_ptr< Device >	removeDevice (uint32_t id)
	Removes device with given ID from device map. More...

std::vector< std::shared_ptr< Device > >	getDeviceList ()
	Returns a copy of the list of active USB devices. More...

std::vector< std::shared_ptr< Device > >	getDeviceList (const Rule &query)
	Returns a copy of the list of active USB devices with rule that applies to given query. More...

std::shared_ptr< Device >	getDevice (uint32_t id)
	Returns device from a device map with a given ID. More...

std::mutex &	refDeviceMapMutex ()
	Returns reference to device map mutex. More...

void	DeviceEvent (EventType event, std::shared_ptr< Device > device)
	Acknowledges daemon instance hooks about given event. More...

void	DeviceException (const std::string &message)
	Acknowledges daemon instance hooks about given exception. More...

Static Public Member Functions
static uint32_t	eventTypeToInteger (EventType event)
	Casts event to it's integer representation. More...

static EventType	eventTypeFromInteger (uint32_t event_integer)
	Converts integer to it's event representation. More...

static std::string	eventTypeToString (EventType event)
	Converts event to it's string representation. More...

static int32_t	authorizedDefaultTypeToInteger (AuthorizedDefaultType authorized_default)
	Casts authorized default to it's integer representation. More...

static AuthorizedDefaultType	authorizedDefaultTypeFromInteger (int32_t authorized_default_integer)
	Converts integer to it's authorized default representation. More...

static AuthorizedDefaultType	authorizedDefaultTypeFromString (const std::string &authorized_default_string)
	Converts string to it's authorized default representation. More...

static const std::string	authorizedDefaultTypeToString (AuthorizedDefaultType authorized_default)
	Converts authorized default to it's string representation. More...

static std::shared_ptr< DeviceManager >	create (DeviceManagerHooks &hooks, const std::string &backend)
	Creates `UEventDeviceManager` if backend is "uevent" or creates `UMockDevDeviceManager` if backend is "umockdev". More...

Detailed Description

Manages and keeps track of active USB devices.

Devices are stored in the device map. When an event occurs on a device, the device manager aknowledges the hooks about the event.

Member Enumeration Documentation

◆ AuthorizedDefaultType

enum usbguard::DeviceManager::AuthorizedDefaultType

strong

Defines which devices are authorized by default.

Enumerator
Keep	Do not change the authorization state.
Wired	New wired USB devices start out authorized, wireless USB devices do not.
None	Every new device starts out deauthorized.
All	Every new device starts out authorized.
Internal	Internal devices start out authorized, external devices start out deauthorized (this requires the ACPI tables to properly label internal devices, and kernel support).

◆ EventType

enum usbguard::DeviceManager::EventType

strong

Type of event that took place on the device.

Enumerator
Present	USB device has been already present.
Insert	USB device has been inserted.
Update	Some writable attribute has been changed externally.
Remove	USB device has been ejected.

Constructor & Destructor Documentation

◆ DeviceManager() [1/2]

usbguard::DeviceManager::DeviceManager ( DeviceManagerHooks & hooks )

Constructs new device manager object with given hooks.

Parameters

hooks Device manager hook that will get notified when an event or an exception occurs.

◆ DeviceManager() [2/2]

usbguard::DeviceManager::DeviceManager ( const DeviceManager & rhs )

Constructs new device manager from a given device manager.

Parameters

rhs	Device manager to copy.

Member Function Documentation

◆ applyDevicePolicy()

virtual std::shared_ptr<Device> usbguard::DeviceManager::applyDevicePolicy	(	uint32_t	id,
		Rule::Target	target
	)

pure virtual

Applies given policy to device with given ID.

Parameters

id	ID of the device to which policy should be applied.
target	Policy to apply.

Returns: Device with given ID and applied policy.

◆ authorizedDefaultTypeFromInteger()

DeviceManager::AuthorizedDefaultType usbguard::DeviceManager::authorizedDefaultTypeFromInteger ( int32_t authorized_default_integer )

static

Converts integer to it's authorized default representation.

Parameters

authorized_default_integer Integer that should be converted.

Returns: Authorized default for given integer.

Exceptions

runtime_error If given integer is not a valid authorized default.

◆ authorizedDefaultTypeFromString()

DeviceManager::AuthorizedDefaultType usbguard::DeviceManager::authorizedDefaultTypeFromString ( const std::string & authorized_default_string )

static

Converts string to it's authorized default representation.

Parameters

authorized_default_string String that should be converted.

Returns: Authorized default for given string.

Exceptions

Exception If given string does not contain valid authorized default.

◆ authorizedDefaultTypeToInteger()

int32_t usbguard::DeviceManager::authorizedDefaultTypeToInteger ( DeviceManager::AuthorizedDefaultType authorized_default )

static

Casts authorized default to it's integer representation.

Parameters

authorized_default Authorized default to cast to integer.

Returns: Integer representation of given authorized default.

◆ authorizedDefaultTypeToString()

const std::string usbguard::DeviceManager::authorizedDefaultTypeToString ( AuthorizedDefaultType authorized_default )

static

Converts authorized default to it's string representation.

Parameters

authorized_default Authorized default that should be converted.

Returns: String representation of given authorized default.

Exceptions

USBGUARD_BUG If given authorized default is invalid.

◆ create()

std::shared_ptr< usbguard::DeviceManager > usbguard::DeviceManager::create	(	DeviceManagerHooks &	hooks,
		const std::string &	backend
	)

static

Creates UEventDeviceManager if backend is "uevent" or creates UMockDevDeviceManager if backend is "umockdev".

uevent - Netlink based implementation which uses sysfs to scan for present devices and an uevent netlink socket for receiving USB device related events.
umockdev - Umockdev based device manager capable of simulating devices based on umockdev-record files. Useful for testing.

Deprecated:
Backend "udev" is obsolete and "uevent" should be used instead.

Parameters

hooks	Device manager hooks.
backend	Type of device manager to create.

Returns: Object of type UEventDeviceManager or UMockDevDeviceManager based on chosen backend.

Exceptions

Exception If given backend is invalid.

◆ DeviceEvent()

void usbguard::DeviceManager::DeviceEvent	(	DeviceManager::EventType	event,
		std::shared_ptr< Device >	device
	)

Acknowledges daemon instance hooks about given event.

Calls dmHookDeviceEvent() on object registered as hook.

Parameters

event	Event that arose.
device	Device that is part of the event.

See also: dmHookDeviceEvent()

◆ DeviceException()

void usbguard::DeviceManager::DeviceException ( const std::string & message )

Acknowledges daemon instance hooks about given exception.

Calls dmHookDeviceException() on object registered as hook.

Parameters

message Message of the exception.

See also: dmHookDeviceException()

◆ eventTypeFromInteger()

DeviceManager::EventType usbguard::DeviceManager::eventTypeFromInteger ( uint32_t event_integer )

static

Converts integer to it's event representation.

Parameters

event_integer Integer that should be converted.

Returns: event for given integer.

Exceptions

runtime_error If given integer is not a valid event.

◆ eventTypeToInteger()

uint32_t usbguard::DeviceManager::eventTypeToInteger ( DeviceManager::EventType event )

static

Casts event to it's integer representation.

Parameters

event Event to cast to integer.

Returns: Integer representation of given event.

◆ eventTypeToString()

std::string usbguard::DeviceManager::eventTypeToString ( DeviceManager::EventType event )

static

Converts event to it's string representation.

Parameters

event Event that should be converted.

Returns: String representation of given event.

Exceptions

USBGUARD_BUG If given event is invalid.

◆ getAuthorizedDefault()

DeviceManager::AuthorizedDefaultType usbguard::DeviceManager::getAuthorizedDefault ( ) const

Returns current authorized default setting.

Returns: Current authorized default setting.

See also: AuthorizedDefaultType

◆ getDevice()

std::shared_ptr< Device > usbguard::DeviceManager::getDevice ( uint32_t id )

Returns device from a device map with a given ID.

Parameters

id	ID of the device.

Returns: Device from a device map with a given ID.

Exceptions

Exception If there is no device with such ID in device map.

◆ getDeviceList() [1/2]

std::vector< std::shared_ptr< Device > > usbguard::DeviceManager::getDeviceList ( )

Returns a copy of the list of active USB devices.

Returns: Copy of the list of active USB devices.

◆ getDeviceList() [2/2]

std::vector< std::shared_ptr< Device > > usbguard::DeviceManager::getDeviceList ( const Rule & query )

Returns a copy of the list of active USB devices with rule that applies to given query.

Parameters

query Rule to apply to.

Returns: Copy of the list of active USB devices with rule that applies to given query.

See also: appliesTo()

◆ getRestoreControllerDeviceState()

bool usbguard::DeviceManager::getRestoreControllerDeviceState ( ) const

Returns true if restore controller device state is enabled, false otherwise.

Returns: True if restore controller device state is enabled, false otherwise.

◆ insertDevice()

void usbguard::DeviceManager::insertDevice ( std::shared_ptr< Device > device )

virtual

Adds new device into a device map.

Device ID will be assigned by the device manager hooks.

Parameters

device Device to be added into map of devices.

◆ operator=()

const DeviceManager & usbguard::DeviceManager::operator= ( const DeviceManager & rhs )

Constructs new device manager based on given device manager and assignes it to this.

Parameters

rhs	Device manager to copy.

◆ refDeviceMapMutex()

std::mutex& usbguard::DeviceManager::refDeviceMapMutex ( )

Returns reference to device map mutex.

Returns: Reference to device map mutex.

◆ removeDevice()

std::shared_ptr< Device > usbguard::DeviceManager::removeDevice ( uint32_t id )

Removes device with given ID from device map.

Parameters

id	ID of the device that shall be removed.

Returns: Device that has been removed.

Exceptions

Exception If device with such ID does not exist in device map.

◆ scan()

virtual void usbguard::DeviceManager::scan ( const std::string & devpath )

pure virtual

Scan for USB devices on given path.

Parameters

devpath Path to scan.

◆ setAuthorizedDefault()

void usbguard::DeviceManager::setAuthorizedDefault ( DeviceManager::AuthorizedDefaultType authorized )

Enables you to set the default authorization of USB devices.

Parameters

authorized authorized default to be set.

See also: AuthorizedDefaultType

◆ setEnumerationOnlyMode()

virtual void usbguard::DeviceManager::setEnumerationOnlyMode ( bool state )

pure virtual

When a device is inserted into a system it's authorized default will stay unchanged.

Parameters

state If true, enables enumeration only mode.

◆ setRestoreControllerDeviceState()

void usbguard::DeviceManager::setRestoreControllerDeviceState ( bool enabled )

Controls whether USBGuard daemon tries to restore the device attribute values to the state before modification on shutdown.

The USBGuard daemon modifies some attributes of controller devices like the default authorization state of new child device instances. Using this setting, you can control whether the daemon will try to restore the attribute values to the state before modification on shutdown.

Warning: If set to true, the USB authorization policy could be bypassed by performing some sort of attack on the daemon (via local exploit or via a USB device) to make it shutdown and restore to the operating-system default state (known to be permissive).

Parameters

enabled Value to be set.

The documentation for this class was generated from the following files:

DeviceManager.hpp
DeviceManager.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ AuthorizedDefaultType

◆ EventType

Constructor & Destructor Documentation

◆ DeviceManager() [1/2]

◆ DeviceManager() [2/2]

Member Function Documentation

◆ applyDevicePolicy()

◆ authorizedDefaultTypeFromInteger()

◆ authorizedDefaultTypeFromString()

◆ authorizedDefaultTypeToInteger()

◆ authorizedDefaultTypeToString()

◆ create()

◆ DeviceEvent()

◆ DeviceException()

◆ eventTypeFromInteger()

◆ eventTypeToInteger()

◆ eventTypeToString()

◆ getAuthorizedDefault()

◆ getDevice()

◆ getDeviceList() [1/2]

◆ getDeviceList() [2/2]

◆ getRestoreControllerDeviceState()

◆ insertDevice()

◆ operator=()

◆ refDeviceMapMutex()

◆ removeDevice()

◆ scan()

◆ setAuthorizedDefault()

◆ setEnumerationOnlyMode()

◆ setRestoreControllerDeviceState()