Skip to content

New design: policies

Jump to bottom
Frans van Dorsselaer edited this page Apr 17, 2024 · 2 revisions

This is work in progress. Discussion at https://github.com/dorssel/usbipd-win/discussions/910.

Draft implementation: https://github.com/dorssel/usbipd-win/pull/916

New commands

usbipd policy list
usbipd policy add --effect <EFFECT> --operation <OPERATION> [--busid <BUSID>] [--hardware-id <VID:PID>]
usbipd policy remove --guid <GUID>
usbipd policy remove --all

add and remove will require Administrator privileges.

For now, EFFECT must be either Allow or Deny (case insensitive). In the future, it may include Audit, ...

For now, OPERATION must be AutoBind (case insensitive). In the future, it maybe could be Attach, ...

For add, at least one of the condition must be provided (--busid or --hardware-id), but both may be provided.

New rules (with add) will be assigned a GUID, which is listed with list and can be used to remove.

Effects

remote usbip list

Currently (without the policy system), a remote list will only list devices that are connected to the host (plugged in) and bound (usbipd bind has been used).

With the new policy system, the list will also include devices that are connected to the host and explicitly allowed and not explicitly denied. This means devices may show up in the list of exported devices even if they have not been bound, making them available to attach anyway.

remote usbip attach

Currently (without the policy system), a remote attach will only (try to) attach devices that are connected to the host (plugged in) and bound (usbipd bind has been used).

With the new policy system, if a device is not bound but is explicitly allowed and not explicitly denied, then the device will first be "auto-bound". That means the device is first recorded as bound "as if" usbipd bind was called by an Administrator. Of course, the attach is then immediately attempted. As a result, if the allow or deny rules are changed after an attach, the device is still bound. In other words, the allow/deny rules are only persistently effective at the time the first attach is attempted. If the device that is bound needs to be removed from the list of "allowed devices", an Administrator will have to usbipd unbind, just like before.

This also means that a "deny" has no effect on currently bound devices.

Flow

flowchart TD

A[remote `usbip list` or `usbip attach`] --> B{"(in case of list: for each device)\nIs the device bound?"}
B -- Yes --> C[Use the device: list it or attempt attach]
B -- No --> D{Does the device match an allow rule?}

D -- Yes --> E{Does the device match a deny rule?}
E -- Yes --> F[Don't list the device, or 'not found' for attach]
D -- No --> F
E -- No --> G[Only for `attach`, not for `list`:\nBind the device 'as if' `usbipd bind`]
G --> C

From the diagram it is clear that the addition only affects devices that are currently unbound. And that the effect is that the device ends up to be bound (in the old sense). Hence, the feature could be called "auto-bind" and the policy rules "auto-bind" rules.

Considerations

  1. usbipd-win has a lot of current users. Changing "too much" results in many reported issues from people that are used to old syntax (tried and tested...). Therefore, any additions should be just that: "additions", not "changes".
  2. the addition with this design is "device centric". Although it could be used in the future to add selectors for "clients" (e.g., based on IP). That is currently out of scope. Maybe (just maybe) in the future "firewall-like" selection rules may be added, or a separate "client centric" rule system will be added.
  3. The selectors could be augmented in the future to select on different device criteria. E.g., serial number, device type, etc. That is currently out of scope.
  4. The "deny rules" could have been used to deny already bound devices. That, however, would be a "change". With this design, the rules only take effect at the time of listing (i.e., more devices could be listed than before) and/or at the time of attach (i.e., they will be auto-bound). Therefore, it truly is an "addition" without changing current functionality.
  5. The way devices are bound/attached in the current code requires bookkeeping in the registry. This is not affected by this addition. It was the reason to make the rules "auto-bind" rules. The rules take effect by utilizing the current bookkeeping mechanism.
  6. devices that are auto-bound by this new feature will not support auto-binding with --force. Forced binding (i.e., permanently replacing the device driver with the stub drivers) will always require explicit Administrator usbipd bind --force. Forced binding is needed only when incompatible USB filter drivers are present; it has always been a workaround, not intended practice.

Use cases

  1. As a developer, I use a lot of different devices. I have a dedicated USB port where I plug in devices under development. I do not want to have to use Administrator prompts for every individual device. I just want to be able to attach all devices plugged into that specific USB port. Use: usbdip policy add --effect allow --operation AutoBind --busid <BUSID>.
  2. As an administrator I want to allow my non-privileged users to be able to attach a specific device, even though it is currently not plugged in. Use: usbipd policy add --effect allow --operation AutoBind --hardware-id <VID:PID>.
  3. As an administrator I want to allow my non-privileged developers to be able to attach any device, but deny the company hardware token. Use: usbdip policy --effect allow --operation AutoBind --busid <BUSID> and usbipd policy add --effect deny --operation AutoBind --hardware-id <VID:PID>.
Clone this wiki locally