Represents USB device in USBGuard. More...

#include <Device.hpp>

Public Member Functions
	Device (DeviceManager &manager)
	Constructs new device object and sets its device manager. More...

virtual	~Device ()
	Default destructor.

	Device (const Device &rhs)
	Constructs device object based on rhs. More...

const Device &	operator= (const Device &rhs)
	Assigns rhs to this. More...

DeviceManager &	manager () const
	Returns device manager that is responsible for this device. More...

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

std::shared_ptr< Rule >	getDeviceRule (bool with_port=true, bool with_parent_hash=true, bool match_rule=false)
	Generates device rule for this USB device. More...

std::string	hashString (const std::string &value) const
	Hashes a given string and returns it. More...

void	initializeHash ()
	Initialize hash for this device. More...

void	updateHash (const void *ptr, size_t size)
	Hashes given data and creates new hash value. More...

void	updateHash (std::istream &descriptor_stream, size_t expected_size)
	Hashes given descriptor stream and creates new hash value. More...

std::string	finalizeHash ()
	Finalizes hash by encoding it into base64. More...

const std::string &	getHash () const
	Returns device hash. More...

void	setParentHash (const std::string &hash)
	Sets parent hash for this device. More...

void	setID (uint32_t id)
	Sets device ID. More...

uint32_t	getID () const
	Returns device ID. More...

void	setParentID (uint32_t id)
	Sets parent ID for this device. More...

uint32_t	getParentID () const
	Returns parent ID. More...

void	setTarget (Rule::Target target)
	Sets given target for this device. More...

Rule::Target	getTarget () const
	Returns rule target for this device. More...

void	setName (const std::string &name)
	Sets device name. More...

const std::string &	getName () const
	Returns device name. More...

void	setDeviceID (const USBDeviceID &device_id)
	Sets device ID. More...

const USBDeviceID &	getDeviceID () const
	Returns device ID. More...

void	setPort (const std::string &port)
	Sets port through which the device is connected. More...

const std::string &	getPort () const
	Returns port through which the device is connected. More...

void	setSerial (const std::string &serial_number)
	Sets device serial number. More...

const std::string &	getSerial () const
	Returns device serial number. More...

void	setConnectType (const std::string &connect_type)
	Sets device connection type. More...

const std::string &	getConnectType () const
	Returns device connection type. More...

std::vector< USBInterfaceType > &	refMutableInterfaceTypes ()
	Returns reference to mutable vector of interface types of this USB device. More...

const std::vector< USBInterfaceType > &	getInterfaceTypes () const
	Returns reference to vector of interface types of this USB device. More...

virtual bool	isController () const =0
	Checks whether this USB device is a controller or not. More...

virtual std::string	getSystemName () const =0
	Returns absolute path of this USB device. More...

void	loadDeviceDescriptor (USBDescriptorParser parser, const USBDescriptor descriptor)
	Loads device descriptor using given USB descriptor parser. More...

void	loadConfigurationDescriptor (USBDescriptorParser parser, const USBDescriptor descriptor)
	Loads configuration descriptor using given USB descriptor parser. More...

void	loadInterfaceDescriptor (USBDescriptorParser parser, const USBDescriptor descriptor)
	Loads interface descriptor using given USB descriptor parser. More...

void	loadEndpointDescriptor (USBDescriptorParser parser, const USBDescriptor descriptor)
	Loads endpoint descriptor using given USB descriptor parser. More...

Detailed Description

Represents USB device in USBGuard.

Constructor & Destructor Documentation

◆ Device() [1/2]

usbguard::Device::Device ( DeviceManager & manager )

Constructs new device object and sets its device manager.

Device ID is set to default, parent device ID is set to root ID and target rule is set to unknown.

Parameters

manager device manager that is responsible for this device.

See also: DefaultID(); RootID(); Target

◆ Device() [2/2]

usbguard::Device::Device ( const Device & rhs )

Constructs device object based on rhs.

Parameters

rhs	Device object to copy.

Member Function Documentation

◆ finalizeHash()

std::string usbguard::Device::finalizeHash ( )

Finalizes hash by encoding it into base64.

Returns: Finalized hash.

◆ getConnectType()

const std::string & usbguard::Device::getConnectType ( ) const

Returns device connection type.

Returns: Device connection type.

◆ getDeviceID()

const USBDeviceID & usbguard::Device::getDeviceID ( ) const

Returns device ID.

Returns: Device ID.

◆ getDeviceRule()

std::shared_ptr< Rule > usbguard::Device::getDeviceRule	(	bool	with_port = `true`,
		bool	with_parent_hash = `true`,
		bool	match_rule = `false`
	)

Generates device rule for this USB device.

Generated device rule is composed of: ID, rule target, device ID, serial number, connection type, port (optional), interface types, device name, hash, parent hash (optional).

Parameters

with_port	If true, port is included in generated rule.
with_parent_hash	If true, parent hash is included in generated rule.
match_rule	If true, sets rule target to match.

Returns: Device rule for this USB device.

Exceptions

runtime_error If with_parent_hash is true and parent hash value is not available.

◆ getHash()

const std::string & usbguard::Device::getHash ( ) const

Returns device hash.

Returns: Device hash.

Exceptions

USBGUARD_BUG If device hash is not finalized.

See also: finalizeHash()

◆ getID()

uint32_t usbguard::Device::getID ( ) const

Returns device ID.

Returns: Device ID.

◆ getInterfaceTypes()

const std::vector< USBInterfaceType > & usbguard::Device::getInterfaceTypes ( ) const

Returns reference to vector of interface types of this USB device.

Returns: Reference to vector of interface types of this USB device.

◆ getName()

const std::string & usbguard::Device::getName ( ) const

Returns device name.

Returns: Device name.

◆ getParentID()

uint32_t usbguard::Device::getParentID ( ) const

Returns parent ID.

Returns: Parent ID.

◆ getPort()

const std::string & usbguard::Device::getPort ( ) const

Returns port through which the device is connected.

Returns: Port through which the device is connected.

◆ getSerial()

const std::string & usbguard::Device::getSerial ( ) const

Returns device serial number.

Returns: Device serial number.

◆ getSystemName()

virtual std::string usbguard::Device::getSystemName ( ) const

pure virtual

Returns absolute path of this USB device.

Returns: Absolute path of this USB device.

◆ getTarget()

Rule::Target usbguard::Device::getTarget ( ) const

Returns rule target for this device.

Returns: Rule target for this device.

See also: Target

◆ hashString()

std::string usbguard::Device::hashString ( const std::string & value ) const

Hashes a given string and returns it.

Parameters

value Value to hash.

Returns: Hashed input string.

◆ initializeHash()

void usbguard::Device::initializeHash ( )

Initialize hash for this device.

Hash is initialized from name, vendor ID, product ID and serial number of the device.

Exceptions

Exception If vendor or product ID is empty.

◆ isController()

virtual bool usbguard::Device::isController ( ) const

pure virtual

Checks whether this USB device is a controller or not.

Returns: True if this USB device is a controller, false otherwise.

◆ loadConfigurationDescriptor()

void usbguard::Device::loadConfigurationDescriptor	(	USBDescriptorParser *	parser,
		const USBDescriptor *	descriptor
	)

Loads configuration descriptor using given USB descriptor parser.

Parameters

parser	Parser that will parse the configuration descriptor.
descriptor	Configuration descriptor.

Exceptions

runtime_error If parent device descriptor is missing while trying to load configuration descriptor.

◆ loadDeviceDescriptor()

void usbguard::Device::loadDeviceDescriptor	(	USBDescriptorParser *	parser,
		const USBDescriptor *	descriptor
	)

Loads device descriptor using given USB descriptor parser.

Parameters

parser	Parser that will parse the USB device descriptor.
descriptor	USB Device descriptor.

Exceptions

runtime_error If there are multiple device descriptors for one device.

◆ loadEndpointDescriptor()

void usbguard::Device::loadEndpointDescriptor	(	USBDescriptorParser *	parser,
		const USBDescriptor *	descriptor
	)

Loads endpoint descriptor using given USB descriptor parser.

Note: Warning: This method can receive USB descriptors of two sizes! (enpoint, audio endpoint).

Parameters

parser	Parser that will parse the endpoint descriptor.
descriptor	Endpoint descriptor.

Exceptions

runtime_error If parent interface descriptor is missing while trying to load enpoint descriptor.

◆ loadInterfaceDescriptor()

void usbguard::Device::loadInterfaceDescriptor	(	USBDescriptorParser *	parser,
		const USBDescriptor *	descriptor
	)

Loads interface descriptor using given USB descriptor parser.

Parameters

parser	Parser that will parse the interface descriptor.
descriptor	Interface descriptor.

Exceptions

runtime_error If parent configuration descriptor is missing while trying to load interface descriptor.

◆ manager()

DeviceManager & usbguard::Device::manager ( ) const

Returns device manager that is responsible for this device.

Returns: Device manager that is responsible for this device.

◆ operator=()

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

Assigns rhs to this.

Parameters

rhs	Device object to assign.

Returns: This object.

◆ refDeviceMutex()

std::mutex & usbguard::Device::refDeviceMutex ( )

Returns reference to device mutex.

Returns: Reference to device mutex.

◆ refMutableInterfaceTypes()

std::vector< USBInterfaceType > & usbguard::Device::refMutableInterfaceTypes ( )

Returns reference to mutable vector of interface types of this USB device.

Returns: Reference to mutable vector of interface types of this USB device.

◆ setConnectType()

void usbguard::Device::setConnectType ( const std::string & connect_type )

Sets device connection type.

Parameters

connect_type Connection type to set.

Exceptions

runtime_error If given connection_type is bigger then USB_GENERIC_STRING_MAX_LENGTH.

◆ setDeviceID()

void usbguard::Device::setDeviceID ( const USBDeviceID & device_id )

Sets device ID.

Parameters

device_id Device ID to set.

◆ setID()

void usbguard::Device::setID ( uint32_t id )

Sets device ID.

Parameters

id	Device ID to set.

◆ setName()

void usbguard::Device::setName ( const std::string & name )

Sets device name.

Parameters

name	Device name to set.

Exceptions

Exception If given name is bigger then USB_GENERIC_STRING_MAX_LENGTH.

◆ setParentHash()

void usbguard::Device::setParentHash ( const std::string & hash )

Sets parent hash for this device.

Parameters

hash	Parent hash to set.

◆ setParentID()

void usbguard::Device::setParentID ( uint32_t id )

Sets parent ID for this device.

Parameters

id	Parent ID to set.

◆ setPort()

void usbguard::Device::setPort ( const std::string & port )

Sets port through which the device is connected.

Parameters

port	Port to set.

Exceptions

runtime_error If given port is bigger then USB_PORT_STRING_MAX_LENGTH.

◆ setSerial()

void usbguard::Device::setSerial ( const std::string & serial_number )

Sets device serial number.

Parameters

serial_number Serial number to set.

Exceptions

runtime_error If given serial_number is bigger then USB_GENERIC_STRING_MAX_LENGTH.

◆ setTarget()

void usbguard::Device::setTarget ( Rule::Target target )

Sets given target for this device.

Parameters

target Target to set.

See also: Target

◆ updateHash() [1/2]

void usbguard::Device::updateHash	(	const void *	ptr,
		size_t	size
	)

Hashes given data and creates new hash value.

Parameters

ptr	Pointer to data to hash.
size	Number of bytes to hash.

◆ updateHash() [2/2]

void usbguard::Device::updateHash	(	std::istream &	descriptor_stream,
		size_t	expected_size
	)

Hashes given descriptor stream and creates new hash value.

Parameters

descriptor_stream	Descriptor stream to hash.
expected_size	Expected number of bytes to hash.

Exceptions

Exception If descriptor stream didnt return expected amount of data.

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

Device.hpp
Device.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Device() [1/2]

◆ Device() [2/2]

Member Function Documentation

◆ finalizeHash()

◆ getConnectType()

◆ getDeviceID()

◆ getDeviceRule()

◆ getHash()

◆ getID()

◆ getInterfaceTypes()

◆ getName()

◆ getParentID()

◆ getPort()

◆ getSerial()

◆ getSystemName()

◆ getTarget()

◆ hashString()

◆ initializeHash()

◆ isController()

◆ loadConfigurationDescriptor()

◆ loadDeviceDescriptor()

◆ loadEndpointDescriptor()

◆ loadInterfaceDescriptor()

◆ manager()

◆ operator=()

◆ refDeviceMutex()

◆ refMutableInterfaceTypes()

◆ setConnectType()

◆ setDeviceID()

◆ setID()

◆ setName()

◆ setParentHash()

◆ setParentID()

◆ setPort()

◆ setSerial()

◆ setTarget()

◆ updateHash() [1/2]

◆ updateHash() [2/2]