[PATCH 15/32] docs: formatdomain-devices: Split out <smartcard>
Peter Krempa
pkrempa at redhat.com
Thu Jul 23 13:21:20 UTC 2020
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
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
More information about the libvir-list
mailing list