[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[libvirt] [RFC: PATCH 1/n] smartcard: add XML support for <smartcard> device



Assuming a hypervisor that supports multiple smartcard devices in the
guest, this would be a valid XML description:

<devices>
  <smartcard mode='host'/>
  <smartcard mode='host-certificates'>
    <certificate>/path/to/cert1</certificate>
    <certificate>/path/to/cert2</certificate>
    <certificate>/path/to/cert3</certificate>
  </smartcard>
  <smartcard mode='passthrough' type='tcp'>
    <source mode='connect' host='127.0.0.1' service='2001'/>
    <protocol type='raw'/>
  </smartcard>
</devices>

* docs/formatdomain.html.in (Smartcard devices): New section.
* docs/schemas/domain.rng (smartcard): New define, used in
devices.
* tests/qemuxml2argvdata/qemuxml2argv-smartcard-host.xml: New file
to test schema.
* tests/qemuxml2argvdata/qemuxml2argv-smartcard-host-certificates.xml:
Likewise.
* tests/qemuxml2argvdata/qemuxml2argv-smartcard-passthrough-tcp.xml:
Likewise.
---

Figuring it's easier to discuss alternatives with a documentation
patch in hand, here's what I've got so far.  My next task is to
update conf/domain_conf.c to parse the new XML, then to teach
qemu/qemu_command.c how to represent it on the command line.

After that, I'll revisit figuring out how to support spicevmc
chardevs, for both vdagent and smartcard.

It looks like 'virsh domxml-from-native qemu-argv file' has
suffered some bit-rot, as it doesn't know how to parse existing
-chardev/-device pairings from valid qemu 0.12+ command lines;
so for now I will focus on the XML->native direction, and leave
improvements to the native->XML direction for another day.

 docs/formatdomain.html.in                          |   72 ++++++++++++++++++++
 docs/schemas/domain.rng                            |   35 ++++++++++
 .../qemuxml2argv-smartcard-host-certificates.xml   |   20 ++++++
 .../qemuxml2argv-smartcard-host.xml                |   16 +++++
 .../qemuxml2argv-smartcard-passthrough-tcp.xml     |   19 +++++
 5 files changed, 162 insertions(+), 0 deletions(-)
 create mode 100644 tests/qemuxml2argvdata/qemuxml2argv-smartcard-host-certificates.xml
 create mode 100644 tests/qemuxml2argvdata/qemuxml2argv-smartcard-host.xml
 create mode 100644 tests/qemuxml2argvdata/qemuxml2argv-smartcard-passthrough-tcp.xml

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index e9fcea1..bf46106 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -799,6 +799,78 @@
       not used by qemu.</dd>
     </dl>

+    <h4><a name="elementsSmartcard">Smartcard devices</a></h4>
+
+    <p>
+      A virtual smartcard device can be supplied to the guest via the
+      <code>smartcard</code> 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. <span class="since">Since 0.8.8</span>
+    </p>
+
+<pre>
+  ...
+  &lt;devices&gt;
+    &lt;smartcard mode='host'/&gt;
+    &lt;smartcard mode='host-certificates'&gt;
+      &lt;certificate&gt;/path/to/cert1&lt;/certificate&gt;
+      &lt;certificate&gt;/path/to/cert2&lt;/certificate&gt;
+      &lt;certificate&gt;/path/to/cert3&lt;/certificate&gt;
+    &lt;/smartcard&gt;
+    &lt;smartcard mode='passthrough' type='tcp'&gt;
+      &lt;source mode='connect' host='127.0.0.1' service='2001'/&gt;
+      &lt;protocol type='raw'/&gt;
+    &lt;/smartcard&gt;
+  &lt;/devices&gt;
+  ...
+</pre>
+
+    <p>
+      The <code>&lt;smartcard&gt;</code> element has a mandatory
+      attribute <code>mode</code>.  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.
+    </p>
+
+    <ul>
+      <li><code>mode='host'</code> &mdash; 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.</li>
+
+      <li><code>mode='host-certificates'</code> &mdash; rather than
+      requiring a smartcard to be plugged into the host, it is
+      possible to provide three files residing on the host and
+      containing NSS certificates.  These certificates can be
+      generated via the command <code>certutil -d /etc/pki/nssdb -x -t
+      CT,CT,CT -S -s CN=cert1 -n cert1</code>, and the resulting three
+      files must be supplied as the content of each of
+      three <code>&lt;certificate&gt;</code> sub-elements.</li>
+
+      <li><code>mode='passthrough'</code> &mdash; 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 <code>type</code> is
+      required, which matches the types of one of the
+      supported <a href="#elementsConsole">serial devices</a>.
+      Further sub-elements, such as <code>&lt;source&gt;</code> are
+      required according to the given type, although
+      a <code>&lt;target&gt;</code> sub-element is not required (since
+      the consumer of the character device is the hypervisor itself,
+      rather than a device visible in the guest).  Use
+      of <code>type='tcp'</code> is most common.</li>
+    </ul>
+
+
     <h4><a name="elementsNICS">Network interfaces</a></h4>

 <pre>
diff --git a/docs/schemas/domain.rng b/docs/schemas/domain.rng
index a524e4b..385d1b6 100644
--- a/docs/schemas/domain.rng
+++ b/docs/schemas/domain.rng
@@ -1579,6 +1579,40 @@
       </interleave>
     </element>
   </define>
+  <define name="smartcard">
+    <element name="smartcard">
+      <choice>
+        <attribute name="mode">
+          <value>host</value>
+        </attribute>
+        <group>
+          <attribute name="mode">
+            <value>host-certificates</value>
+          </attribute>
+          <ref name='certificate'/>
+          <ref name='certificate'/>
+          <ref name='certificate'/>
+        </group>
+        <group>
+          <attribute name="mode">
+            <value>passthrough</value>
+          </attribute>
+          <ref name="qemucdevSrcType"/>
+          <interleave>
+            <ref name="qemucdevSrcDef"/>
+            <optional>
+              <ref name="qemucdevTgtDef"/>
+            </optional>
+          </interleave>
+        </group>
+      </choice>
+    </element>
+  </define>
+  <define name="certificate">
+    <element name="certificate">
+      <ref name="absFilePath"/>
+    </element>
+  </define>
   <define name="input">
     <element name="input">
       <attribute name="type">
@@ -1736,6 +1770,7 @@
             <ref name="parallel"/>
             <ref name="serial"/>
             <ref name="channel"/>
+            <ref name="smartcard"/>
           </choice>
         </zeroOrMore>
         <optional>
diff --git a/tests/qemuxml2argvdata/qemuxml2argv-smartcard-host-certificates.xml b/tests/qemuxml2argvdata/qemuxml2argv-smartcard-host-certificates.xml
new file mode 100644
index 0000000..f70395d
--- /dev/null
+++ b/tests/qemuxml2argvdata/qemuxml2argv-smartcard-host-certificates.xml
@@ -0,0 +1,20 @@
+<domain type='qemu'>
+  <name>QEMUGuest1</name>
+  <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+  <memory>219200</memory>
+  <currentMemory>219200</currentMemory>
+  <vcpu>1</vcpu>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <devices>
+    <emulator>/usr/bin/qemu</emulator>
+    <smartcard mode='host-certificates'>
+      <certificate>/etc/pki/cert1</certificate>
+      <certificate>/etc/pki/cert2</certificate>
+      <certificate>/etc/pki/cert3</certificate>
+    </smartcard>
+    <memballoon model='virtio'/>
+  </devices>
+</domain>
diff --git a/tests/qemuxml2argvdata/qemuxml2argv-smartcard-host.xml b/tests/qemuxml2argvdata/qemuxml2argv-smartcard-host.xml
new file mode 100644
index 0000000..faa2231
--- /dev/null
+++ b/tests/qemuxml2argvdata/qemuxml2argv-smartcard-host.xml
@@ -0,0 +1,16 @@
+<domain type='qemu'>
+  <name>QEMUGuest1</name>
+  <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+  <memory>219200</memory>
+  <currentMemory>219200</currentMemory>
+  <vcpu>1</vcpu>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <devices>
+    <emulator>/usr/bin/qemu</emulator>
+    <smartcard mode='host'/>
+    <memballoon model='virtio'/>
+  </devices>
+</domain>
diff --git a/tests/qemuxml2argvdata/qemuxml2argv-smartcard-passthrough-tcp.xml b/tests/qemuxml2argvdata/qemuxml2argv-smartcard-passthrough-tcp.xml
new file mode 100644
index 0000000..8e2fa52
--- /dev/null
+++ b/tests/qemuxml2argvdata/qemuxml2argv-smartcard-passthrough-tcp.xml
@@ -0,0 +1,19 @@
+<domain type='qemu'>
+  <name>QEMUGuest1</name>
+  <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+  <memory>219200</memory>
+  <currentMemory>219200</currentMemory>
+  <vcpu>1</vcpu>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <devices>
+    <emulator>/usr/bin/qemu</emulator>
+    <smartcard mode='passthrough' type='tcp'>
+      <source mode='connect' host='127.0.0.1' service='2001'/>
+      <protocol type='raw'/>
+    </smartcard>
+    <memballoon model='virtio'/>
+  </devices>
+</domain>
-- 
1.7.3.4


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]