libusb: capsicumize libusb

FreeBSD's libusb has three components: libusb01, libusb10, and libusb20.

libusb20 handles communication with character devices. We now requires a
backend context for libusb20. The backend context contains contains the
capsicumized usbctrl fd and usb directory (/dev/usb) fd so that the
library user can enter the capiblity mode safely while using libusb.

libusb10 is updated to support capabilities via a context option. Since
libusb allows general read/write access, we preserve all possible
capabilities when passing backend context to libusb20. It is the
responsibility of the libusb user to call cap_enter() at an appropriate
time.

All base system tools using libusb and libusb20 have been updated to
support Capsicum.

Reviewed by:    adrian, markj
Sponsored by: The FreeBSD Foundation
Differential Revision: https://reviews.freebsd.org/D51865

1 files changed, 17 insertions, 0 deletions

diff --git a/lib/libusb/libusb.3 b/lib/libusb/libusb.3
index 42b2e90f148e..a946e998df9e 100644
--- a/lib/libusb/libusb.3
+++ b/lib/libusb/libusb.3
@@ -945,8 +945,25 @@ The library is also compliant with LibUSB version 0.1.12.
 .Fn usb_get_driver_np
 .Fn usb_detach_kernel_driver_np
 .Fn usb_attach_kernel_driver_np
+.Sh CAPABILITY MODE
+Every
+.Nm
+context opens the file descriptors needed to reach the USB devices at
+.Fn libusb_init
+time and opens device nodes relative to a per-context directory
+descriptor using
+.Xr openat 2 .
+All operations on the context, including enumeration of hotplugged
+devices, therefore keep working after entering capability mode, see
+.Xr capsicum 4 .
+The file descriptors are limited with
+.Xr cap_rights_limit 2 .
+Initialise the context before calling
+.Xr cap_enter 2 .
 .Sh SEE ALSO
+.Xr cap_enter 2 ,
 .Xr libusb20 3 ,
+.Xr capsicum 4 ,
 .Xr usb 4 ,
 .Xr usbconfig 8 ,
 .Xr usbdump 8