From patchwork Wed Mar 9 17:39:29 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Berger X-Patchwork-Id: 595159 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org 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 ozlabs.org (Postfix) with ESMTPS id B665A140BCD for ; Thu, 10 Mar 2016 04:39:51 +1100 (AEDT) Received: from localhost ([127.0.0.1] helo=sfs-ml-1.v29.ch3.sourceforge.com) by sfs-ml-1.v29.ch3.sourceforge.com with esmtp (Exim 4.76) (envelope-from ) id 1adi5J-0007PP-F1; Wed, 09 Mar 2016 17:39:45 +0000 Received: from sog-mx-1.v43.ch3.sourceforge.com ([172.29.43.191] helo=mx.sourceforge.net) by sfs-ml-1.v29.ch3.sourceforge.com with esmtp (Exim 4.76) (envelope-from ) id 1adi5I-0007PK-TL for tpmdd-devel@lists.sourceforge.net; Wed, 09 Mar 2016 17:39:44 +0000 X-ACL-Warn: Received: from e17.ny.us.ibm.com ([129.33.205.207]) by sog-mx-1.v43.ch3.sourceforge.com with esmtps (TLSv1:AES256-SHA:256) (Exim 4.76) id 1adi5H-0002v0-RY for tpmdd-devel@lists.sourceforge.net; Wed, 09 Mar 2016 17:39:44 +0000 Received: from localhost by e17.ny.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Wed, 9 Mar 2016 12:39:38 -0500 Received: from d01dlp01.pok.ibm.com (9.56.250.166) by e17.ny.us.ibm.com (146.89.104.204) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Wed, 9 Mar 2016 12:39:36 -0500 X-IBM-Helo: d01dlp01.pok.ibm.com X-IBM-MailFrom: stefanb@linux.vnet.ibm.com X-IBM-RcptTo: tpmdd-devel@lists.sourceforge.net Received: from b01cxnp23032.gho.pok.ibm.com (b01cxnp23032.gho.pok.ibm.com [9.57.198.27]) by d01dlp01.pok.ibm.com (Postfix) with ESMTP id EE73B38C8026 for ; Wed, 9 Mar 2016 12:39:35 -0500 (EST) Received: from d01av01.pok.ibm.com (d01av01.pok.ibm.com [9.56.224.215]) by b01cxnp23032.gho.pok.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id u29HdZpC19398898 for ; Wed, 9 Mar 2016 17:39:35 GMT Received: from d01av01.pok.ibm.com (localhost [127.0.0.1]) by d01av01.pok.ibm.com (8.14.4/8.14.4/NCO v10.0 AVout) with ESMTP id u29HdZR5021304 for ; Wed, 9 Mar 2016 12:39:35 -0500 Received: from dhcp-9-2-140-43.watson.ibm.com (dhcp-9-2-140-28.watson.ibm.com [9.2.140.28]) by d01av01.pok.ibm.com (8.14.4/8.14.4/NCO v10.0 AVin) with ESMTP id u29HdW4M020852; Wed, 9 Mar 2016 12:39:35 -0500 From: Stefan Berger To: tpmdd-devel@lists.sourceforge.net Date: Wed, 9 Mar 2016 12:39:29 -0500 Message-Id: <1457545170-30120-11-git-send-email-stefanb@linux.vnet.ibm.com> X-Mailer: git-send-email 2.4.3 In-Reply-To: <1457545170-30120-1-git-send-email-stefanb@linux.vnet.ibm.com> References: <1457545170-30120-1-git-send-email-stefanb@linux.vnet.ibm.com> X-TM-AS-MML: disable X-Content-Scanned: Fidelis XPS MAILER x-cbid: 16030917-0041-0000-0000-000003865E9F X-Spam-Score: -0.0 (/) X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. -0.0 RP_MATCHES_RCVD Envelope sender domain matches handover relay domain X-Headers-End: 1adi5H-0002v0-RY Cc: linux-doc@vger.kernel.org, linux-api@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [tpmdd-devel] [PATCH v6 10/11] tpm: Add documentation for the tpm_vtpm 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 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. Signed-off-by: Stefan Berger CC: linux-kernel@vger.kernel.org CC: linux-doc@vger.kernel.org CC: linux-api@vger.kernel.org --- Documentation/tpm/tpm_vtpm.txt | 54 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 Documentation/tpm/tpm_vtpm.txt diff --git a/Documentation/tpm/tpm_vtpm.txt b/Documentation/tpm/tpm_vtpm.txt new file mode 100644 index 0000000..d193573 --- /dev/null +++ b/Documentation/tpm/tpm_vtpm.txt @@ -0,0 +1,54 @@ +Virtual TPM Device Driver for Linux Containers + +Authors: Stefan Berger (IBM) + +This document describes the virtual Trusted Platform Module (vTPM) 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 device 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 VTPM_NEW_DEV ioctl: + +struct vtpm_new_dev { + __u32 flags; /* input */ + __u32 dev_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.h for definitions related to the public interface +of this vTPM device driver.