org.usbguard.Devices

Name

org.usbguard.Devices -- 

Methods

listDevices       (IN  s     query,
                   OUT a(us) devices);
applyDevicePolicy (IN  u     id,
                   IN  u     target,
                   IN  b     permanent,
                   OUT u     rule_id);

Signals

DevicePresenceChanged (u     id,
                       u     event,
                       s     target,
                       s     device_rule,
                       a{ss} attributes);
DevicePolicyChanged   (u     id,
                       u     target_old,
                       u     target_new,
                       u     device_rule,
                       u     rule_id,
                       a{ss} attributes);

Description

The org.usbguard.Devices interface provides access to USB devices via the USBGuard daemon. It can be used to modify the runtime authorization state of devices and to listen for device events (insertion, removal, (de)authorization, ...)

Method Details

The listDevices() method

listDevices (IN  s     query,
             OUT a(us) devices);

List devices that match the specified query. The query uses the rule language syntax and the devices are returned as device specific rules. The target in each rule represents the current authorization state of the device. Order of the returned devices is not defined and should not be relied upon.

Example queries: - 'match': Matches any device. - 'allow': Matches only authorized devices. - 'block': Matches only unauthorized devices. - 'match with-interface one-of { 03:00:01 03:01:01 }': Matches any device with a HID/Keyboard interface.

IN s query:

A query, in the rule language syntax, for matching devices.

OUT a(us) devices:

An array of (device_id, device_rule) tuples that match the query.

The applyDevicePolicy() method

applyDevicePolicy (IN  u id,
                   IN  u target,
                   IN  b permanent,
                   OUT u rule_id);

0 = Allow. 1 = Block. 2 = Reject. permanent: A boolean flag specifying whether an allow rule should be appended to the policy. rule_id: If permanent was set to true, the method will return an ID of the rule that was modified or created because of this request.

Apply an authorization target to a device.

If the permanent flag is set to True, a rule will be appended to the policy or an exiting device rule will be modified in order to permanently store the authorization decision.

Sucessfull exection of this method will cause the DevicePolicyChanged signal to be broadcasted if the device authorization target was different than the applied target.

IN u id:

Device id of the device to authorize.

IN u target:

Device authorization target in numerical form.

IN b permanent:

OUT u rule_id:

Signal Details

The "DevicePresenceChanged" signal

DevicePresenceChanged (u     id,
                       u     event,
                       s     target,
                       s     device_rule,
                       a{ss} attributes);

0 = Present, 1 = Insert, 2 = Update, 3 = Remove. target: The current authorization target of the device. device_rule: Device specific rule. attributes: A dictionary of device attributes and their values.

Notify that a USB device was already present when USBGuard was started. Note that currently this signal is of little use to 3rd-party application developers as the signal won't reach any clients on the bus because the bus connections are handled after the devices are processed. However, the internal processing routines may change in the future so this signal is provided and documented for completeness.

The device attribute dictionary contains the following attributes: - id (the USB device ID in the form VID:PID) - name - serial - via-port - hash - parent-hash - with-interface

The USB interface types are represented as strings of the form AA:BB:CC, where AA, BB, and CC are hexadecimal numbers representing the class, subclass and protocol of the interface as defined by the USB standard.

u id:

Device id of the device.

u event:

Type of the presence change event in numerical form.

s target:

s device_rule:

a{ss} attributes:

The "DevicePolicyChanged" signal

DevicePolicyChanged (u     id,
                     u     target_old,
                     u     target_new,
                     u     device_rule,
                     u     rule_id,
                     a{ss} attributes);

Notify about a change of a USB device authorization target.

The device attribute dictionary contains the following attributes: - id (the USB device ID in the form VID:PID) - name - serial - via-port - hash - parent-hash - with-interface

u id:

Device id of the device

u target_old:

Previous authorization target in numerical form.

u target_new:

Current authorization target in numerical form.

u device_rule:

u rule_id:

A rule id of the matched rule. Otherwise a reserved rule id value is used.

a{ss} attributes:

A dictionary of device attributes and their values.