From patchwork Fri Dec 9 16:17:10 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Cedric Bosdonnat X-Patchwork-Id: 9468593 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id E585F607D8 for ; Fri, 9 Dec 2016 16:19:56 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D5E912864E for ; Fri, 9 Dec 2016 16:19:55 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id CAC1C28652; Fri, 9 Dec 2016 16:19:55 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-3.7 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, URI_NOVOWEL autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 892662864E for ; Fri, 9 Dec 2016 16:19:54 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cFNrW-000853-4V; Fri, 09 Dec 2016 16:17:30 +0000 Received: from mail6.bemta6.messagelabs.com ([193.109.254.103]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cFNrU-00082t-V0 for xen-devel@lists.xen.org; Fri, 09 Dec 2016 16:17:29 +0000 Received: from [85.158.143.35] by server-9.bemta-6.messagelabs.com id 25/C5-28694-819DA485; Fri, 09 Dec 2016 16:17:28 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFlrIIsWRWlGSWpSXmKPExsVyuP0uq674Ta8 Ig9+zuSyWfFzM4sDocXT3b6YAxijWzLyk/IoE1ox5T48yFbRMZqw48OULUwPj5uIuRi4OIYEl jBI/e7YxdjFycrAJ2Et0/TnKBGKLCEhLXPt8mRGkiFngD6PEiUPTmbsYOTiEBcwlJl1SADFZB FQlDr1yBzF5BSwkJqyoAumUEJCX2NV2kRXE5hSwlLh09gs7iC0EVLJk4XmwOK+AoMTJmU9YQF qZBdQl1s8TAgkzA7U2b53NPIGRdxaSqlkIVbOQVC1gZF7FqFGcWlSWWqRrZKaXVJSZnlGSm5i Zo2toYKaXm1pcnJiempOYVKyXnJ+7iREYUAxAsIPxzILAQ4ySHExKorzFTF4RQnxJ+SmVGYnF GfFFpTmpxYcYZTg4lCR4718HygkWpaanVqRl5gBDGyYtwcGjJMIbcAMozVtckJhbnJkOkTrFa Mwx7dnip0wc604tecokxJKXn5cqJc57HWSSAEhpRmke3CBYzF1ilJUS5mUEOk2IpyC1KDezBF X+FaM4B6OSMK8syEKezLwSuH2vgE5hAjpl3g13kFNKEhFSUg2Mt6Jj7N+cmOp9M0f6WvstQ5c rnz/NmifyXjPZv6n31Uo7szmprSmrF+d3tytKGBk/c50l+l7olTv7r9Ume5xaDxcnvpzdoKce vSndPGxFz4rJPlNXxqnMZtFTciv5oi9sG/3RhHPW0ytzvid8EHYq9cz77Jef8EHj27SQWZahZ /gZbxx/uyRWiaU4I9FQi7moOBEAfiBnSrQCAAA= X-Env-Sender: cbosdonnat@suse.com X-Msg-Ref: server-2.tower-21.messagelabs.com!1481300246!33584362!1 X-Originating-IP: [195.135.221.5] X-SpamReason: No, hits=0.0 required=7.0 tests= X-StarScan-Received: X-StarScan-Version: 9.1.1; banners=-,-,- X-VirusChecked: Checked Received: (qmail 21487 invoked from network); 9 Dec 2016 16:17:27 -0000 Received: from smtp.nue.novell.com (HELO smtp.nue.novell.com) (195.135.221.5) by server-2.tower-21.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 9 Dec 2016 16:17:27 -0000 Received: from laptop.vms (mhy71-2-88-167-63-197.fbx.proxad.net [88.167.63.197]) by smtp.nue.novell.com with ESMTP (TLS encrypted); Fri, 09 Dec 2016 17:17:25 +0100 From: =?UTF-8?q?C=C3=A9dric=20Bosdonnat?= To: xen-devel@lists.xen.org Date: Fri, 9 Dec 2016 17:17:10 +0100 Message-Id: <20161209161714.23866-8-cbosdonnat@suse.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20161209161714.23866-1-cbosdonnat@suse.com> References: <20161209161714.23866-1-cbosdonnat@suse.com> MIME-Version: 1.0 Cc: Quan Xu , Wei Liu , Andrew Cooper , Ian Jackson , =?UTF-8?q?C=C3=A9dric=20Bosdonnat?= , Daniel De Graaf Subject: [Xen-devel] [PATCH 07/11] docs: move vtpm from misc to man X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP vtpm.txt is referenced in xl.cfg man page. Convert it to pod, move it to the man folder and update the reference. Signed-off-by: Cédric Bosdonnat --- docs/INDEX | 1 - docs/{misc/vtpm.txt => man/vtpm.pod.7} | 364 +++++++++++++++++---------------- docs/man/xl.cfg.pod.5.in | 3 +- 3 files changed, 194 insertions(+), 174 deletions(-) rename docs/{misc/vtpm.txt => man/vtpm.pod.7} (57%) diff --git a/docs/INDEX b/docs/INDEX index 101d43c7aa..66cc82b78c 100644 --- a/docs/INDEX +++ b/docs/INDEX @@ -18,7 +18,6 @@ misc/xenstore-paths Xenstore path documentation misc/distro_mapping Distro Directory Layouts misc/dump-core-format Xen Core Dump Format misc/vtd VT-d HOWTO -misc/vtpm Virtual TPM misc/xen-error-handling Xen Error Handling misc/xenpaging Xen Paging misc/xsm-flask XSM/FLASK Configuration diff --git a/docs/misc/vtpm.txt b/docs/man/vtpm.pod.7 similarity index 57% rename from docs/misc/vtpm.txt rename to docs/man/vtpm.pod.7 index 1887d40d25..03bde1d4eb 100644 --- a/docs/misc/vtpm.txt +++ b/docs/man/vtpm.pod.7 @@ -7,9 +7,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for Xen. The reader is assumed to have familiarity with building and installing Xen, Linux, and a basic understanding of the TPM and vTPM concepts. ------------------------------- -INTRODUCTION ------------------------------- +=head1 INTRODUCTION + The goal of this work is to provide a TPM functionality to a virtual guest operating system (a DomU). This allows programs to interact with a TPM in a virtual system the same way they interact with a TPM on the physical system. @@ -25,99 +24,114 @@ mini-os to reduce memory and processor overhead. This mini-os vTPM subsystem was built on top of the previous vTPM work done by IBM and Intel corporation. ------------------------------- -DESIGN OVERVIEW ------------------------------- +=head1 DESIGN OVERVIEW The architecture of vTPM is described below: -+------------------+ -| Linux DomU | ... -| | ^ | -| v | | -| xen-tpmfront | -+------------------+ - | ^ - v | -+------------------+ -| mini-os/tpmback | -| | ^ | -| v | | -| vtpm-stubdom | ... -| | ^ | -| v | | -| mini-os/tpmfront | -+------------------+ - | ^ - v | -+------------------+ -| mini-os/tpmback | -| | ^ | -| v | | -| vtpmmgr-stubdom | -| | ^ | -| v | | -| mini-os/tpm_tis | -+------------------+ - | ^ - v | -+------------------+ -| Hardware TPM | -+------------------+ - * Linux DomU: The Linux based guest that wants to use a vTPM. There many be - more than one of these. - - * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver - provides vTPM access to a para-virtualized Linux based DomU. - - * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver - connects to this backend driver to facilitate - communications between the Linux DomU and its vTPM. This - driver is also used by vtpmmgr-stubdom to communicate with - vtpm-stubdom. - - * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a - one to one mapping between running vtpm-stubdom instances and - logical vtpms on the system. The vTPM Platform Configuration - Registers (PCRs) are all initialized to zero. - - * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain - vtpm-stubdom uses this driver to communicate with - vtpmmgr-stubdom. This driver could also be used separately to - implement a mini-os domain that wishes to use a vTPM of - its own. - - * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. - There is only one vTPM manager and it should be running during - the entire lifetime of the machine. This domain regulates - access to the physical TPM on the system and secures the - persistent state of each vTPM. - - * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS) - driver. This driver used by vtpmmgr-stubdom to talk directly to - the hardware TPM. Communication is facilitated by mapping - hardware memory pages into vtpmmgr-stubdom. - - * Hardware TPM: The physical TPM that is soldered onto the motherboard. - ------------------------------- -INSTALLATION ------------------------------- - -Prerequisites: --------------- + +------------------+ + | Linux DomU | ... + | | ^ | + | v | | + | xen-tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpm-stubdom | ... + | | ^ | + | v | | + | mini-os/tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpmmgr-stubdom | + | | ^ | + | v | | + | mini-os/tpm_tis | + +------------------+ + | ^ + v | + +------------------+ + | Hardware TPM | + +------------------+ + +=over 4 + +=item Linux DomU + +The Linux based guest that wants to use a vTPM. There many be +more than one of these. + +=item xen-tpmfront.ko + +Linux kernel virtual TPM frontend driver. This driver +provides vTPM access to a para-virtualized Linux based DomU. + +=item mini-os/tpmback + +Mini-os TPM backend driver. The Linux frontend driver +connects to this backend driver to facilitate +communications between the Linux DomU and its vTPM. This +driver is also used by vtpmmgr-stubdom to communicate with +vtpm-stubdom. + +=item vtpm-stubdom + +A mini-os stub domain that implements a vTPM. There is a +one to one mapping between running vtpm-stubdom instances and +logical vtpms on the system. The vTPM Platform Configuration +Registers (PCRs) are all initialized to zero. + +=item mini-os/tpmfront + +Mini-os TPM frontend driver. The vTPM mini-os domain +vtpm-stubdom uses this driver to communicate with +vtpmmgr-stubdom. This driver could also be used separately to +implement a mini-os domain that wishes to use a vTPM of +its own. + +=item vtpmmgr-stubdom + +A mini-os domain that implements the vTPM manager. +There is only one vTPM manager and it should be running during +the entire lifetime of the machine. This domain regulates +access to the physical TPM on the system and secures the +persistent state of each vTPM. + +=item mini-os/tpm_tis + +Mini-os TPM version 1.2 TPM Interface Specification (TIS) +driver. This driver used by vtpmmgr-stubdom to talk directly to +the hardware TPM. Communication is facilitated by mapping +hardware memory pages into vtpmmgr-stubdom. + +=item Hardware TPM + +The physical TPM that is soldered onto the motherboard. + +=back + +=head1 INSTALLATION + +=head2 Prerequisites: + You must have an x86 machine with a TPM on the motherboard. The only extra software requirement for compiling vTPM is cmake. You must use libxl to manage domains with vTPMs; 'xm' is deprecated and does not support vTPMs. -Compiling the Xen tree: ------------------------ +=head2 Compiling the Xen tree: Compile and install the Xen tree as usual; be sure that the vTPM domains are enabled when you run configure. -Compiling the LINUX dom0 kernel: --------------------------------- +=head2 Compiling the LINUX dom0 kernel: Because the TPM manager uses direct access to the physical TPM, it may interfere with access to the TPM by dom0. The simplest solution for this is to prevent @@ -137,30 +151,25 @@ a later time. If a vTPM gets an error when loading its key, it will currently generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM). -Compiling the LINUX domU kernel: --------------------------------- +=head2 Compiling the LINUX domU kernel: The domU kernel used by domains with vtpms must include the xen-tpmfront.ko driver. It can be built directly into the kernel or as a module; however, some features such as IMA require the TPM to be built in to the kernel. -CONFIG_TCG_TPM=y -CONFIG_TCG_XEN=y + CONFIG_TCG_TPM=y + CONFIG_TCG_XEN=y ------------------------------- -VTPM MANAGER SETUP ------------------------------- +=head1 VTPM MANAGER SETUP -Manager disk image setup: -------------------------- +=head2 Manager disk image setup: The vTPM Manager requires a disk image to store its encrypted data. The image does not require a filesystem and can live anywhere on the host disk. The image is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image but can support more than 20,000 vTPMs. -Manager config file: --------------------- +=head2 Manager config file: The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen virtual machine and requires a config file. The manager requires a disk image @@ -172,8 +181,7 @@ uses locality 0 (so only the page at 0xfed40 is needed); this can be changed on the domain's command line. For full functionality in deep quotes, using locality 2 is required to manipulate PCR 20-22. -Starting and stopping the manager: ----------------------------------- +=head2 Starting and stopping the manager: The vTPM manager should be started at boot; you may wish to create an init script to do this. If a domain builder is used, the TPM Manager should be @@ -181,43 +189,39 @@ started by the domain builder to minimize the trusted computing base for the vTPM manager's secrets. Once initialization is complete you should see the following: -INFO[VTPM]: Waiting for commands from vTPM's: + + INFO[VTPM]: Waiting for commands from vTPM's: The TPM Manager does not respond to shutdown requests; use the destroy command to shut it down. ------------------------------- -VTPM AND LINUX PVM SETUP ------------------------------- +=head1 VTPM AND LINUX PVM SETUP -vTPM disk image setup: ----------------------- +=head2 vTPM disk image setup: The vTPM requires a disk image to store its persistent data (RSA keys, NVRAM, etc). The image does not require a filesystem. The image does not need to be large; 2 Mb should be sufficient. -vTPM config file: ------------------ +=head2 vTPM config file: The vTPM domain requires a configuration file like any other domain. The vTPM requires a disk image for storage and a TPM frontend driver to communicate with the manager. You are required to generate a uuid for this vtpm, which is -specified on the "vtpm=" line that describes its connection to the vTPM Manager. +specified on the C line that describes its connection to the vTPM Manager. The uuidgen application may be used to generate a uuid, or one from the output -of the "manage-vtpmmgr.pl vtpm-add" command may be used to create a vTPM +of the C command may be used to create a vTPM belonging to a specific group. If you wish to clear the vTPM data you can either recreate the disk image or change the uuid. -Linux Guest config file: ------------------------- +=head2 Linux Guest config file: The Linux guest config file needs to be modified to include the Linux tpmfront driver. Add the following line: -vtpm=["backend=domu-vtpm"] + vtpm=["backend=domu-vtpm"] Currently only Linux guests are supported (PV or HVM with PV drivers). @@ -229,34 +233,34 @@ configuration. Attaching a vTPM to a running domain should only be used for trusted domains or when measurements have already been sent to the vTPM from another source. -Using the vTPM in the guest: ----------------------------- +=head2 Using the vTPM in the guest: If xen-tpmfront was compiled as a module, it must be loaded it in the guest. -# modprobe xen-tpmfront + # modprobe xen-tpmfront After the Linux domain boots and the xen-tpmfront driver is loaded, you should see the following on the vtpm console: -Info: VTPM attached to Frontend X/Y + Info: VTPM attached to Frontend X/Y You can quickly test the vTPM by using the sysfs interface: -# cat /sys/devices/vtpm-0/pubek -# cat /sys/devices/vtpm-0/pcrs + # cat /sys/devices/vtpm-0/pubek + # cat /sys/devices/vtpm-0/pcrs If you have trousers and tpm_tools installed on the guest, the tpm_version command should return the following: The version command should return the following: - TPM 1.2 Version Info: - Chip Version: 1.2.0.7 - Spec Level: 2 - Errata Revision: 1 - TPM Vendor ID: ETHZ - TPM Version: 01010000 - Manufacturer Info: 4554485a + + TPM 1.2 Version Info: + Chip Version: 1.2.0.7 + Spec Level: 2 + Errata Revision: 1 + TPM Vendor ID: ETHZ + TPM Version: 01010000 + Manufacturer Info: 4554485a You should also see the command being sent to the vtpm console as well as the vtpm saving its state. You should see the vtpm key being encrypted and stored on @@ -265,9 +269,7 @@ the vtpmmgr console. You may wish to write a script to start your vtpm and guest together and to destroy the vtpm when the guest shuts down. ------------------------------- -INTEGRATION WITH PV-GRUB ------------------------------- +=head1 INTEGRATION WITH PV-GRUB The vTPM currently starts up with all PCRs set to their default values (all zeros for the lower 16). This means that any decisions about the @@ -283,16 +285,12 @@ extend the hash of the kernel that it boots into PCR #4, and will extend the command line and initrd into PCR #5 before booting so that a domU booted in this way can attest to its early boot state. ------------------------------- -MORE INFORMATION ------------------------------- +=head1 MORE INFORMATION -See vtpmmgr.txt for more details about how the manager domain works, how to use +See for more details about how the manager domain works, how to use it, and its command line parameters. ------------------------------- -VTPM DOMAIN OPERATION ------------------------------- +=head1 VTPM DOMAIN OPERATION The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest OS to use. It is a small wrapper around the Berlios TPM emulator version 0.7.4. @@ -302,54 +300,78 @@ machine. The key used to encrypt the data along with a hash of the vTPM's data is sent to the vTPM manager for secure storage and later retrieval. The vTPM domain communicates with the manager using a mini-os tpm front/back device pair. ------------------------------------- -VTPM DOMAIN COMMAND LINE ARGUMENTS ------------------------------------- +=head1 VTPM DOMAIN COMMAND LINE ARGUMENTS Command line arguments are passed to the domain via the 'extra' parameter in the VM config file. Each parameter is separated by white space. For example: -extra="foo=bar baz" + extra="foo=bar baz" + +=head2 List of Arguments: + +=over 4 + +=item B= + +Controls the amount of logging printed to the console. +The possible values for are: + +=over 4 + +=item * error + +=item * info (default) + +=item * debug + +=back + +=item B + +Start the Berlios emulator in "clear" mode. (default) + +=item B + +Start the Berlios emulator in "save" mode. + +=item B + +Start the Berlios emulator in "deactivated" mode. +See the Berlios TPM emulator documentation for details +about the startup mode. For all normal use, always use clear +which is the default. You should not need to specify any of these. + +=item B=<1|0> + +Enable to disable the TPM maintenance commands. +These commands are used by tpm manufacturers and thus +open a security hole. They are disabled by default. + +=item B= + +Initialize the virtual Platform Configuration Registers +(PCRs) with PCR values from the hardware TPM. Each pcr specified by + will be initialized with the value of that same PCR in TPM +once at startup. By default all PCRs are zero initialized. +Possible values of are: -List of Arguments: ------------------- +=over -loglevel=: Controls the amount of logging printed to the console. - The possible values for are: - error - info (default) - debug +=item * all: copy all pcrs -clear: Start the Berlios emulator in "clear" mode. (default) +=item * none: copy no pcrs (default) -save: Start the Berlios emulator in "save" mode. +=item * : copy pcr n -deactivated: Start the Berlios emulator in "deactivated" mode. - See the Berlios TPM emulator documentation for details - about the startup mode. For all normal use, always use clear - which is the default. You should not need to specify any of these. +=item * : copy pcrs x to y (inclusive) -maintcmds=<1|0>: Enable to disable the TPM maintenance commands. - These commands are used by tpm manufacturers and thus - open a security hole. They are disabled by default. +=back -hwinitpcr=: Initialize the virtual Platform Configuration Registers - (PCRs) with PCR values from the hardware TPM. Each pcr specified by - will be initialized with the value of that same PCR in TPM - once at startup. By default all PCRs are zero initialized. - Value values of are: - all: copy all pcrs - none: copy no pcrs (default) - : copy pcr n - : copy pcrs x to y (inclusive) +These can also be combined by comma separation, for example: +C will copy pcrs 5, 12, 13, 14, 15, and 16. - These can also be combined by comma separation, for example: - hwinitpcrs=5,12-16 - will copy pcrs 5, 12, 13, 14, 15, and 16. +=back ------------------------------- -REFERENCES ------------------------------- +=head1 REFERENCES -Berlios TPM Emulator: -http://tpm-emulator.berlios.de/ +Berlios TPM Emulator: L diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in index fc2faac12b..33fae038f7 100644 --- a/docs/man/xl.cfg.pod.5.in +++ b/docs/man/xl.cfg.pod.5.in @@ -491,8 +491,7 @@ L. =item B Specifies the virtual trusted platform module to be -provided to the guest. Please see F -for more details. +provided to the guest. Please see L for more details. Each B is a comma-separated list of C settings, from the following list: