From patchwork Mon Apr 18 17:26:16 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Berger X-Patchwork-Id: 8874141 Return-Path: X-Original-To: patchwork-tpmdd-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 77C369F1C1 for ; Mon, 18 Apr 2016 17:26:41 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 4B60E20222 for ; Mon, 18 Apr 2016 17:26:40 +0000 (UTC) Received: from lists.sourceforge.net (lists.sourceforge.net [216.34.181.88]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 0CE3B20103 for ; Mon, 18 Apr 2016 17:26:39 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=sfs-ml-4.v29.ch3.sourceforge.com) by sfs-ml-4.v29.ch3.sourceforge.com with esmtp (Exim 4.76) (envelope-from ) id 1asCwX-0000dC-Iu; Mon, 18 Apr 2016 17:26:37 +0000 Received: from sog-mx-3.v43.ch3.sourceforge.com ([172.29.43.193] helo=mx.sourceforge.net) by sfs-ml-4.v29.ch3.sourceforge.com with esmtp (Exim 4.76) (envelope-from ) id 1asCwW-0000cz-Lb for tpmdd-devel@lists.sourceforge.net; Mon, 18 Apr 2016 17:26:36 +0000 X-ACL-Warn: Received: from e33.co.us.ibm.com ([32.97.110.151]) by sog-mx-3.v43.ch3.sourceforge.com with esmtps (TLSv1:AES256-SHA:256) (Exim 4.76) id 1asCwV-0007Ne-KW for tpmdd-devel@lists.sourceforge.net; Mon, 18 Apr 2016 17:26:36 +0000 Received: from localhost by e33.co.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Mon, 18 Apr 2016 11:26:29 -0600 Received: from d03dlp03.boulder.ibm.com (9.17.202.179) by e33.co.us.ibm.com (192.168.1.133) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Mon, 18 Apr 2016 11:26:27 -0600 X-IBM-Helo: d03dlp03.boulder.ibm.com X-IBM-MailFrom: stefanb@linux.vnet.ibm.com X-IBM-RcptTo: tpmdd-devel@lists.sourceforge.net Received: from b01cxnp22033.gho.pok.ibm.com (b01cxnp22033.gho.pok.ibm.com [9.57.198.23]) by d03dlp03.boulder.ibm.com (Postfix) with ESMTP id 9D69C19D804C for ; Mon, 18 Apr 2016 11:14:17 -0600 (MDT) Received: from d01av04.pok.ibm.com (d01av04.pok.ibm.com [9.56.224.64]) by b01cxnp22033.gho.pok.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id u3IHQQfI35127348 for ; Mon, 18 Apr 2016 17:26:26 GMT Received: from d01av04.pok.ibm.com (localhost [127.0.0.1]) by d01av04.pok.ibm.com (8.14.4/8.14.4/NCO v10.0 AVout) with ESMTP id u3IHQP90017226 for ; Mon, 18 Apr 2016 13:26:25 -0400 Received: from dhcp-9-2-140-43.watson.ibm.com (dhcp-9-2-140-54.watson.ibm.com [9.2.140.54]) by d01av04.pok.ibm.com (8.14.4/8.14.4/NCO v10.0 AVin) with ESMTP id u3IHQObh017086; Mon, 18 Apr 2016 13:26:25 -0400 From: Stefan Berger To: tpmdd-devel@lists.sourceforge.net Date: Mon, 18 Apr 2016 13:26:16 -0400 Message-Id: <1461000376-2888-5-git-send-email-stefanb@linux.vnet.ibm.com> X-Mailer: git-send-email 2.4.3 In-Reply-To: <1461000376-2888-1-git-send-email-stefanb@linux.vnet.ibm.com> References: <1461000376-2888-1-git-send-email-stefanb@linux.vnet.ibm.com> X-TM-AS-MML: disable X-Content-Scanned: Fidelis XPS MAILER x-cbid: 16041817-0009-0000-0000-0000214544BA X-Spam-Score: -1.0 (-) X-Headers-End: 1asCwV-0007Ne-KW Cc: linux-doc@vger.kernel.org, linux-api@vger.kernel.org, linux-kernel@vger.kernel.org, linux-security-module@vger.kernel.org Subject: [tpmdd-devel] [PATCH v11 4/4] tpm: Add documentation for the tpm_vtpm_proxy device driver X-BeenThere: tpmdd-devel@lists.sourceforge.net X-Mailman-Version: 2.1.9 Precedence: list List-Id: Tpm Device Driver maintainance List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: tpmdd-devel-bounces@lists.sourceforge.net X-Spam-Status: No, score=-7.9 required=5.0 tests=BAYES_00, HK_RANDOM_ENVFROM, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Add documentation for the tpm_vtpm device driver that implements support for providing TPM functionality to Linux containers. Parts of this documentation were recycled from the Xen vTPM device driver documentation. Update the documentation for the ioctl numbers. Signed-off-by: Stefan Berger Reviewed-by: Jarkko Sakkinen CC: linux-kernel@vger.kernel.org CC: linux-doc@vger.kernel.org CC: linux-api@vger.kernel.org Tested-by: Jarkko Sakkinen --- Documentation/ioctl/ioctl-number.txt | 1 + Documentation/tpm/tpm_vtpm_proxy.txt | 71 ++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 Documentation/tpm/tpm_vtpm_proxy.txt diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 91261a3..7dbec90 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -303,6 +303,7 @@ Code Seq#(hex) Include File Comments 0xA0 all linux/sdp/sdp.h Industrial Device Project +0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver 0xA2 00-0F arch/tile/include/asm/hardwall.h 0xA3 80-8F Port ACL in development: diff --git a/Documentation/tpm/tpm_vtpm_proxy.txt b/Documentation/tpm/tpm_vtpm_proxy.txt new file mode 100644 index 0000000..30d1902 --- /dev/null +++ b/Documentation/tpm/tpm_vtpm_proxy.txt @@ -0,0 +1,71 @@ +Virtual TPM Proxy Driver for Linux Containers + +Authors: Stefan Berger (IBM) + +This document describes the virtual Trusted Platform Module (vTPM) +proxy device driver for Linux containers. + +INTRODUCTION +------------ + +The goal of this work is to provide TPM functionality to each Linux +container. This allows programs to interact with a TPM in a container +the same way they interact with a TPM on the physical system. Each +container gets its own unique, emulated, software TPM. + + +DESIGN +------ + +To make an emulated software TPM available to each container, the container +management stack needs to create a device pair consisting of a client TPM +character device /dev/tpmX (with X=0,1,2...) and a 'server side' file +descriptor. The former is moved into the container by creating a character +device with the appropriate major and minor numbers while the file descriptor +is passed to the TPM emulator. Software inside the container can then send +TPM commands using the character device and the emulator will receive the +commands via the file descriptor and use it for sending back responses. + +To support this, the virtual TPM proxy driver provides a device /dev/vtpmx +that is used to create device pairs using an ioctl. The ioctl takes as +an input flags for configuring the device. The flags for example indicate +whether TPM 1.2 or TPM 2 functionality is supported by the TPM emulator. +The result of the ioctl are the file descriptor for the 'server side' +as well as the major and minor numbers of the character device that was created. +Besides that the number of the TPM character device is return. If for +example /dev/tpm10 was created, the number (dev_num) 10 is returned. + +The following is the data structure of the TPM_PROXY_IOC_NEW_DEV ioctl: + +struct vtpm_proxy_new_dev { + __u32 flags; /* input */ + __u32 tpm_num; /* output */ + __u32 fd; /* output */ + __u32 major; /* output */ + __u32 minor; /* output */ +}; + +Note that if unsupported flags are passed to the device driver, the ioctl will +fail and errno will be set to EOPNOTSUPP. Similarly, if an unsupported ioctl is +called on the device driver, the ioctl will fail and errno will be set to +ENOTTY. + +See /usr/include/linux/vtpm_proxy.h for definitions related to the public interface +of this vTPM device driver. + +Once the device has been created, the driver will immediately try to talk +to the TPM. All commands from the driver can be read from the file descriptor +returned by the ioctl. The commands should be responded to immediately. + +Depending on the version of TPM the following commands will be sent by the +driver: + +- TPM 1.2: + - the driver will send a TPM_Startup command to the TPM emulator + - the driver will send commands to read the command durations and + interface timeouts from the TPM emulator +- TPM 2: + - the driver will send a TPM2_Startup command to the TPM emulator + +The TPM device /dev/tpmX will only appear if all of the relevant commands +were responded to properly.