From nobody Mon Feb 9 00:07:31 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) client-ip=207.211.31.81; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1595510552; cv=none; d=zohomail.com; s=zohoarc; b=ET3BZESXwfKI7MniJCuzVSSJ+PAb4M64+TRY/+Om4OcjgGAXMhBRVhTx3wZMeGUdKdfKp1xzw8W1cRQho0EkH/XUk8JxBioz5uXA/l66I9DWIt1vjXV3qzF9RJJbXqMo3kBkxM/Y1HIZLfmDm5cUxYlhdgJmlm1gnU2SsV6/WV8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510552; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=mvTPVkiuDIX9uOCPd8w5HEKtEyyK1qGbAUjMGHRravs=; b=UpfCe+Oc/ETmM/2cLUt/BJoigJwT5ZKSc/G2FKkSdeOqygbKwHm7tbj4lyoUcLz1SvhzBsMMTBEVRi3KGQubtCYYpX41gMMDrgRLg+ZtDYrHE11w4/OxBvXULUOHsKwZjMMZc8fcSiwFUHdfM5rQhwMn0ubxDg0EGYYcBTKtvTU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [207.211.31.81]) by mx.zohomail.com with SMTPS id 1595510552144567.4982388358143; Thu, 23 Jul 2020 06:22:32 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-473-fQP3-6teO8ePpFM0pgNjng-1; Thu, 23 Jul 2020 09:22:28 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 227C1100944F; Thu, 23 Jul 2020 13:22:22 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 03F4171D3C; Thu, 23 Jul 2020 13:22:22 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id C7F82A3589; Thu, 23 Jul 2020 13:22:21 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDMHbO028582 for ; Thu, 23 Jul 2020 09:22:17 -0400 Received: by smtp.corp.redhat.com (Postfix) id 37B531A922; Thu, 23 Jul 2020 13:22:17 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8F13019D7C for ; Thu, 23 Jul 2020 13:22:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510551; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=mvTPVkiuDIX9uOCPd8w5HEKtEyyK1qGbAUjMGHRravs=; b=GlPGI446IXpvhO4n1Q1aGehbwxIkp3zCGxMApoeLdDhD51WrZjcoJ/eYJeH+jGvjZWObd/ xQL6Gs0pcr8RfAOpXLin/XaApM2M2A3Gwhs8XD4/zNUI+cfGOQmHdhcddkpuFarNtkPzmA ErtvS7aV8EAVMb9TfQjDmVnpXdAMKKI= X-MC-Unique: fQP3-6teO8ePpFM0pgNjng-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 15/32] docs: formatdomain-devices: Split out Date: Thu, 23 Jul 2020 15:21:20 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- 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-de= vices-smartcard.rst new file mode 100644 index 0000000000..8853bd2681 --- /dev/null +++ b/docs/formatdomain-devices-smartcard.rst @@ -0,0 +1,71 @@ +:anchor:`` + +Smartcard devices +~~~~~~~~~~~~~~~~~ + +A virtual smartcard device can be supplied to the guest via the ``smartcar= d`` +element. A USB smartcard reader device on the host cannot be used on a gue= st +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 smartc= ard +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` + +:: + + ... + + + + cert1 + cert2 + cert3 + /etc/pki/nssdb/ + + + + +
+ + + + ... + +The ```` element has a mandatory attribute ``mode``. The follow= ing +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 t= he + guest into direct access to the host's smartcard via NSS. No other attr= ibutes + or sub-elements are required. See below about the use of an optional + ``
`` sub-element. +``host-certificates`` + Rather than requiring a smartcard to be plugged into the host, it is po= ssible + to provide three NSS certificate names residing in a database on the ho= st. + These certificates can be generated via the command + ``certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=3Dcert1 -n c= ert1``, + and the resulting three certificate names must be supplied as the conte= nt of + each of three ```` sub-elements. An additional sub-element + ```` can specify the absolute path to an alternate directory + (matching the ``-d`` option of the ``certutil`` command when creating t= he + certificates); if not present, it defaults to /etc/pki/nssdb. +``passthrough`` + Rather than having the hypervisor directly communicate with the host, i= t 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 us= ing + three certificate files). In this mode of operation, an additional attr= ibute + ``type`` is required, matching one of the supported `serial + device <#elementsConsole>`__ types, to describe the host side of the tu= nnel; + ``type=3D'tcp'`` or ``type=3D'spicevmc'`` (which uses the smartcard cha= nnel of a + `SPICE graphics device <#elementsGraphics>`__) are typical. Further + sub-elements, such as ````, may be required according to the gi= ven + type, although a ```` sub-element is not required (since the co= nsumer + of the character device is the hypervisor itself, rather than a device + visible in the guest). + +Each mode supports an optional sub-element ``
``, which fine-tunes= the +correlation between the smartcard and a ccid bus controller, `documented +above <#elementsAddress>`__. For now, qemu only supports at most one smart= card, +with an address of bus=3D0 slot=3D0. 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:`` - -Smartcard devices -~~~~~~~~~~~~~~~~~ - -A virtual smartcard device can be supplied to the guest via the ``smartcar= d`` -element. A USB smartcard reader device on the host cannot be used on a gue= st -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 smartc= ard -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` - -:: - - ... - - - - cert1 - cert2 - cert3 - /etc/pki/nssdb/ - - - - -
- - - - ... - -The ```` element has a mandatory attribute ``mode``. The follow= ing -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 t= he - guest into direct access to the host's smartcard via NSS. No other attr= ibutes - or sub-elements are required. See below about the use of an optional - ``
`` sub-element. -``host-certificates`` - Rather than requiring a smartcard to be plugged into the host, it is po= ssible - to provide three NSS certificate names residing in a database on the ho= st. - These certificates can be generated via the command - ``certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=3Dcert1 -n c= ert1``, - and the resulting three certificate names must be supplied as the conte= nt of - each of three ```` sub-elements. An additional sub-element - ```` can specify the absolute path to an alternate directory - (matching the ``-d`` option of the ``certutil`` command when creating t= he - certificates); if not present, it defaults to /etc/pki/nssdb. -``passthrough`` - Rather than having the hypervisor directly communicate with the host, i= t 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 us= ing - three certificate files). In this mode of operation, an additional attr= ibute - ``type`` is required, matching one of the supported `serial - device <#elementsConsole>`__ types, to describe the host side of the tu= nnel; - ``type=3D'tcp'`` or ``type=3D'spicevmc'`` (which uses the smartcard cha= nnel of a - `SPICE graphics device <#elementsGraphics>`__) are typical. Further - sub-elements, such as ````, may be required according to the gi= ven - type, although a ```` sub-element is not required (since the co= nsumer - of the character device is the hypervisor itself, rather than a device - visible in the guest). - -Each mode supports an optional sub-element ``
``, which fine-tunes= the -correlation between the smartcard and a ccid bus controller, `documented -above <#elementsAddress>`__. For now, qemu only supports at most one smart= card, -with an address of bus=3D0 slot=3D0. +.. include:: formatdomain-devices-smartcard.rst :anchor:`` 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 =3D [ 'formatdomain-devices-lease.rst', 'formatdomain-devices-hostdev.rst', 'formatdomain-devices-redirdev.rst', + 'formatdomain-devices-smartcard.rst', ] }, { 'name': 'hacking' }, --=20 2.26.2