[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