[PATCH 15/32] docs: formatdomain-devices: Split out <smartcard>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-smartcard.rst | 71 ++++++++++++++++++++++++ docs/formatdomain-devices.rst | 73 +------------------------ docs/meson.build | 1 + 3 files changed, 73 insertions(+), 72 deletions(-) create mode 100644 docs/formatdomain-devices-smartcard.rst diff --git a/docs/formatdomain-devices-smartcard.rst b/docs/formatdomain-devices-smartcard.rst new file mode 100644 index 0000000000..8853bd2681 --- /dev/null +++ b/docs/formatdomain-devices-smartcard.rst @@ -0,0 +1,71 @@ +:anchor:`<a id="elementsSmartcard"/>` + +Smartcard devices +~~~~~~~~~~~~~~~~~ + +A virtual smartcard device can be supplied to the guest via the ``smartcard`` +element. A USB smartcard reader device on the host cannot be used on a guest +with simple device passthrough, since it will then not be available on the host, +possibly locking the host computer when it is "removed". Therefore, some +hypervisors provide a specialized virtual device that can present a smartcard +interface to the guest, with several modes for describing how credentials are +obtained from the host or even a from a channel created to a third-party +smartcard provider. :since:`Since 0.8.8` + +:: + + ... + <devices> + <smartcard mode='host'/> + <smartcard mode='host-certificates'> + <certificate>cert1</certificate> + <certificate>cert2</certificate> + <certificate>cert3</certificate> + <database>/etc/pki/nssdb/</database> + </smartcard> + <smartcard mode='passthrough' type='tcp'> + <source mode='bind' host='127.0.0.1' service='2001'/> + <protocol type='raw'/> + <address type='ccid' controller='0' slot='0'/> + </smartcard> + <smartcard mode='passthrough' type='spicevmc'/> + </devices> + ... + +The ``<smartcard>`` element has a mandatory attribute ``mode``. The following +modes are supported; in each mode, the guest sees a device on its USB bus that +behaves like a physical USB CCID (Chip/Smart Card Interface Device) card. + +``host`` + The simplest operation, where the hypervisor relays all requests from the + guest into direct access to the host's smartcard via NSS. No other attributes + or sub-elements are required. See below about the use of an optional + ``<address>`` sub-element. +``host-certificates`` + Rather than requiring a smartcard to be plugged into the host, it is possible + to provide three NSS certificate names residing in a database on the host. + These certificates can be generated via the command + ``certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=cert1 -n cert1``, + and the resulting three certificate names must be supplied as the content of + each of three ``<certificate>`` sub-elements. An additional sub-element + ``<database>`` can specify the absolute path to an alternate directory + (matching the ``-d`` option of the ``certutil`` command when creating the + certificates); if not present, it defaults to /etc/pki/nssdb. +``passthrough`` + Rather than having the hypervisor directly communicate with the host, it is + possible to tunnel all requests through a secondary character device to a + third-party provider (which may in turn be talking to a smartcard or using + three certificate files). In this mode of operation, an additional attribute + ``type`` is required, matching one of the supported `serial + device <#elementsConsole>`__ types, to describe the host side of the tunnel; + ``type='tcp'`` or ``type='spicevmc'`` (which uses the smartcard channel of a + `SPICE graphics device <#elementsGraphics>`__) are typical. Further + sub-elements, such as ``<source>``, may be required according to the given + type, although a ``<target>`` sub-element is not required (since the consumer + of the character device is the hypervisor itself, rather than a device + visible in the guest). + +Each mode supports an optional sub-element ``<address>``, which fine-tunes the +correlation between the smartcard and a ccid bus controller, `documented +above <#elementsAddress>`__. For now, qemu only supports at most one smartcard, +with an address of bus=0 slot=0. diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index 052d325a56..4b5391f77b 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -47,78 +47,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` .. include:: formatdomain-devices-lease.rst .. include:: formatdomain-devices-hostdev.rst .. include:: formatdomain-devices-redirdev.rst - -:anchor:`<a id="elementsSmartcard"/>` - -Smartcard devices -~~~~~~~~~~~~~~~~~ - -A virtual smartcard device can be supplied to the guest via the ``smartcard`` -element. A USB smartcard reader device on the host cannot be used on a guest -with simple device passthrough, since it will then not be available on the host, -possibly locking the host computer when it is "removed". Therefore, some -hypervisors provide a specialized virtual device that can present a smartcard -interface to the guest, with several modes for describing how credentials are -obtained from the host or even a from a channel created to a third-party -smartcard provider. :since:`Since 0.8.8` - -:: - - ... - <devices> - <smartcard mode='host'/> - <smartcard mode='host-certificates'> - <certificate>cert1</certificate> - <certificate>cert2</certificate> - <certificate>cert3</certificate> - <database>/etc/pki/nssdb/</database> - </smartcard> - <smartcard mode='passthrough' type='tcp'> - <source mode='bind' host='127.0.0.1' service='2001'/> - <protocol type='raw'/> - <address type='ccid' controller='0' slot='0'/> - </smartcard> - <smartcard mode='passthrough' type='spicevmc'/> - </devices> - ... - -The ``<smartcard>`` element has a mandatory attribute ``mode``. The following -modes are supported; in each mode, the guest sees a device on its USB bus that -behaves like a physical USB CCID (Chip/Smart Card Interface Device) card. - -``host`` - The simplest operation, where the hypervisor relays all requests from the - guest into direct access to the host's smartcard via NSS. No other attributes - or sub-elements are required. See below about the use of an optional - ``<address>`` sub-element. -``host-certificates`` - Rather than requiring a smartcard to be plugged into the host, it is possible - to provide three NSS certificate names residing in a database on the host. - These certificates can be generated via the command - ``certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=cert1 -n cert1``, - and the resulting three certificate names must be supplied as the content of - each of three ``<certificate>`` sub-elements. An additional sub-element - ``<database>`` can specify the absolute path to an alternate directory - (matching the ``-d`` option of the ``certutil`` command when creating the - certificates); if not present, it defaults to /etc/pki/nssdb. -``passthrough`` - Rather than having the hypervisor directly communicate with the host, it is - possible to tunnel all requests through a secondary character device to a - third-party provider (which may in turn be talking to a smartcard or using - three certificate files). In this mode of operation, an additional attribute - ``type`` is required, matching one of the supported `serial - device <#elementsConsole>`__ types, to describe the host side of the tunnel; - ``type='tcp'`` or ``type='spicevmc'`` (which uses the smartcard channel of a - `SPICE graphics device <#elementsGraphics>`__) are typical. Further - sub-elements, such as ``<source>``, may be required according to the given - type, although a ``<target>`` sub-element is not required (since the consumer - of the character device is the hypervisor itself, rather than a device - visible in the guest). - -Each mode supports an optional sub-element ``<address>``, which fine-tunes the -correlation between the smartcard and a ccid bus controller, `documented -above <#elementsAddress>`__. For now, qemu only supports at most one smartcard, -with an address of bus=0 slot=0. +.. include:: formatdomain-devices-smartcard.rst :anchor:`<a id="elementsNICS"/>` diff --git a/docs/meson.build b/docs/meson.build index 4ed30cc737..c5600ba4d1 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -132,6 +132,7 @@ docs_rst_files = [ 'formatdomain-devices-lease.rst', 'formatdomain-devices-hostdev.rst', 'formatdomain-devices-redirdev.rst', + 'formatdomain-devices-smartcard.rst', ] }, { 'name': 'hacking' }, -- 2.26.2