1Virtual TPM Proxy Driver for Linux Containers 2 3Authors: Stefan Berger (IBM) 4 5This document describes the virtual Trusted Platform Module (vTPM) 6proxy device driver for Linux containers. 7 8INTRODUCTION 9------------ 10 11The goal of this work is to provide TPM functionality to each Linux 12container. This allows programs to interact with a TPM in a container 13the same way they interact with a TPM on the physical system. Each 14container gets its own unique, emulated, software TPM. 15 16 17DESIGN 18------ 19 20To make an emulated software TPM available to each container, the container 21management stack needs to create a device pair consisting of a client TPM 22character device /dev/tpmX (with X=0,1,2...) and a 'server side' file 23descriptor. The former is moved into the container by creating a character 24device with the appropriate major and minor numbers while the file descriptor 25is passed to the TPM emulator. Software inside the container can then send 26TPM commands using the character device and the emulator will receive the 27commands via the file descriptor and use it for sending back responses. 28 29To support this, the virtual TPM proxy driver provides a device /dev/vtpmx 30that is used to create device pairs using an ioctl. The ioctl takes as 31an input flags for configuring the device. The flags for example indicate 32whether TPM 1.2 or TPM 2 functionality is supported by the TPM emulator. 33The result of the ioctl are the file descriptor for the 'server side' 34as well as the major and minor numbers of the character device that was created. 35Besides that the number of the TPM character device is return. If for 36example /dev/tpm10 was created, the number (dev_num) 10 is returned. 37 38The following is the data structure of the TPM_PROXY_IOC_NEW_DEV ioctl: 39 40struct vtpm_proxy_new_dev { 41 __u32 flags; /* input */ 42 __u32 tpm_num; /* output */ 43 __u32 fd; /* output */ 44 __u32 major; /* output */ 45 __u32 minor; /* output */ 46}; 47 48Note that if unsupported flags are passed to the device driver, the ioctl will 49fail and errno will be set to EOPNOTSUPP. Similarly, if an unsupported ioctl is 50called on the device driver, the ioctl will fail and errno will be set to 51ENOTTY. 52 53See /usr/include/linux/vtpm_proxy.h for definitions related to the public interface 54of this vTPM device driver. 55 56Once the device has been created, the driver will immediately try to talk 57to the TPM. All commands from the driver can be read from the file descriptor 58returned by the ioctl. The commands should be responded to immediately. 59 60Depending on the version of TPM the following commands will be sent by the 61driver: 62 63- TPM 1.2: 64 - the driver will send a TPM_Startup command to the TPM emulator 65 - the driver will send commands to read the command durations and 66 interface timeouts from the TPM emulator 67- TPM 2: 68 - the driver will send a TPM2_Startup command to the TPM emulator 69 70The TPM device /dev/tpmX will only appear if all of the relevant commands 71were responded to properly. 72