PERFORCE change 150179 for review

[Hans Petter Selasky]

http://perforce.freebsd.org/chv.cgi?CH=150179

Change 150179 by hselasky at hselasky_laptop001 on 2008/09/20 19:55:15

	
	Add a chapter about the USB security model.

Affected files ...

.. //depot/projects/usb/src/share/man/man4/usb2_core.4#3 edit

Differences ...

==== //depot/projects/usb/src/share/man/man4/usb2_core.4#3 (text+ko) ====

@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 3, 2008
+.Dd September 20, 2008
 .Dt USB2_CORE 4
 .Os
 .
@@ -31,108 +31,6 @@
 .
 .
 .Nm usb2_core
-.Nm usb2_bdma_done_event,
-.Nm usb2_bdma_post_sync,
-.Nm usb2_bdma_pre_sync,
-.Nm usb2_bdma_work_loop,
-.Nm usb2_bzero,
-.Nm usb2_config_td_drain,
-.Nm usb2_config_td_is_gone,
-.Nm usb2_config_td_queue_command,
-.Nm usb2_config_td_setup,
-.Nm usb2_config_td_sleep,
-.Nm usb2_config_td_unsetup,
-.Nm usb2_copy_in,
-.Nm usb2_copy_in_user,
-.Nm usb2_copy_out,
-.Nm usb2_copy_out_user,
-.Nm usb2_desc_foreach,
-.Nm usb2_dma_tag_find,
-.Nm usb2_dma_tag_setup,
-.Nm usb2_dma_tag_unsetup,
-.Nm usb2_errstr,
-.Nm usb2_fifo_alloc_buffer,
-.Nm usb2_fifo_attach,
-.Nm usb2_fifo_detach,
-.Nm usb2_fifo_free,
-.Nm usb2_fifo_free_buffer,
-.Nm usb2_fifo_get_data,
-.Nm usb2_fifo_get_data_buffer,
-.Nm usb2_fifo_get_data_error,
-.Nm usb2_fifo_get_data_linear,
-.Nm usb2_fifo_get_data_next,
-.Nm usb2_fifo_opened,
-.Nm usb2_fifo_put_bytes_max,
-.Nm usb2_fifo_put_data,
-.Nm usb2_fifo_put_data_buffer,
-.Nm usb2_fifo_put_data_error,
-.Nm usb2_fifo_put_data_linear,
-.Nm usb2_fifo_reset,
-.Nm usb2_fifo_signal,
-.Nm usb2_fifo_wait,
-.Nm usb2_fifo_wakeup,
-.Nm usb2_find_edesc,
-.Nm usb2_find_idesc,
-.Nm usb2_get_bus_index,
-.Nm usb2_get_config_descriptor,
-.Nm usb2_get_device_descriptor,
-.Nm usb2_get_device_index,
-.Nm usb2_get_iface,
-.Nm usb2_get_interface_altindex,
-.Nm usb2_get_interface_descriptor,
-.Nm usb2_get_no_alts,
-.Nm usb2_get_no_endpoints,
-.Nm usb2_get_page,
-.Nm usb2_get_speed,
-.Nm usb2_m_copy_in,
-.Nm usb2_pc_alloc_mem,
-.Nm usb2_pc_cpu_flush,
-.Nm usb2_pc_cpu_invalidate,
-.Nm usb2_pc_dmamap_create,
-.Nm usb2_pc_dmamap_destroy,
-.Nm usb2_pc_free_mem,
-.Nm usb2_pc_load_mem,
-.Nm usb2_proc_csignal,
-.Nm usb2_proc_cwait,
-.Nm usb2_proc_drain,
-.Nm usb2_proc_is_gone,
-.Nm usb2_proc_msignal,
-.Nm usb2_proc_mwait,
-.Nm usb2_proc_setup,
-.Nm usb2_proc_unsetup,
-.Nm usb2_set_alt_interface_index,
-.Nm usb2_set_frame_data,
-.Nm usb2_set_frame_offset,
-.Nm usb2_set_iface_perm,
-.Nm usb2_set_parent_iface,
-.Nm usb2_start_hardware,
-.Nm usb2_transfer_clear_stall,
-.Nm usb2_transfer_drain,
-.Nm usb2_transfer_set_stall,
-.Nm usb2_transfer_setup,
-.Nm usb2_transfer_start,
-.Nm usb2_transfer_stop,
-.Nm usb2_transfer_unsetup,
-.Nm usb2_uiomove,
-.Nm usb_alloc_urb,
-.Nm usb_altnum_to_altsetting,
-.Nm usb_buffer_alloc,
-.Nm usb_buffer_free,
-.Nm usb_clear_halt,
-.Nm usb_control_msg,
-.Nm usb_find_host_endpoint,
-.Nm usb_free_urb,
-.Nm usb_get_intfdata,
-.Nm usb_ifnum_to_if,
-.Nm usb_init_urb,
-.Nm usb_kill_urb,
-.Nm usb_linux_deregister,
-.Nm usb_linux_register,
-.Nm usb_set_interface,
-.Nm usb_set_intfdata,
-.Nm usb_setup_endpoint,
-.Nm usb_submit_urb,
-.Nm usb_unlink_urb
 .
 .Nd "USB core functions"
 .
@@ -591,8 +489,40 @@
 module supports the Linux USB API.
 .
 .
+.
+.
+.Sh USB SECURITY MODEL
+.
+.
+The
+.Nm
+module implements fine grained read and write access based on username
+and group. Access is granted at four levels:
+.
+.Bl -tag
+.It Level 4 - USB interface
+USB interfaces can be given individual access rights.
+.It Level 3 - USB device
+USB devices can be given individual access rights.
+.It Level 2 - USB BUS
+USB busses can be given individual access rights.
+.It Level 1 - USB
+USB as a whole can be given individual access rights.
+.El
+.Pp
+The
+.Nm
+module will search for access rights starting at level 4 continuing
+downwards to USB at level 1. For critical applications you should be
+aware that the outgoing serial BUS traffic will be broadcasted to all
+USB devices. For absolute security USB devices that require different
+access rights should not be placed on the same USB BUS or controller.
+If connected to the same USB bus, it is possible that a USB device can
+sniff and intercept the communication of another USB device. Using USB
+HUBs will not solve this problem.
 .Sh SEE ALSO
 .Xr usb2_controller 4
+.Xr usbconfig 8
 .Sh STANDARDS
 The
 .Nm