From 9e355ba76455d6d44f5cf888eee820ae9a06b3ec Mon Sep 17 00:00:00 2001 From: Jarkko Sakkinen Date: Thu, 3 Nov 2016 17:57:51 -0600 Subject: tpm: transition tpm_vtpm_proxy documentation to the Sphinx Transitioned the tpm_vtpm_proxy documentation to the Sphinx infrastructure and removed parts from the documentation that are easier to pull from the sources. Restructured vtpm_proxy.h and tpm_vtpm_proxy.c to be compatible with this approach and wrote associated documentation comments. Signed-off-by: Jarkko Sakkinen Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + Documentation/tpm/index.rst | 7 ++++ Documentation/tpm/tpm_vtpm_proxy.rst | 50 +++++++++++++++++++++++++ Documentation/tpm/tpm_vtpm_proxy.txt | 71 ------------------------------------ 4 files changed, 58 insertions(+), 71 deletions(-) create mode 100644 Documentation/tpm/index.rst create mode 100644 Documentation/tpm/tpm_vtpm_proxy.rst delete mode 100644 Documentation/tpm/tpm_vtpm_proxy.txt (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc729..0058b65 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -19,6 +19,7 @@ Contents: media/dvb-drivers/index media/v4l-drivers/index gpu/index + tpm/index Indices and tables ================== diff --git a/Documentation/tpm/index.rst b/Documentation/tpm/index.rst new file mode 100644 index 0000000..af77a7b --- /dev/null +++ b/Documentation/tpm/index.rst @@ -0,0 +1,7 @@ +===================================== +Trusted Platform Module documentation +===================================== + +.. toctree:: + + tpm_vtpm_proxy diff --git a/Documentation/tpm/tpm_vtpm_proxy.rst b/Documentation/tpm/tpm_vtpm_proxy.rst new file mode 100644 index 0000000..ea08e76 --- /dev/null +++ b/Documentation/tpm/tpm_vtpm_proxy.rst @@ -0,0 +1,50 @@ +============================================= +Virtual TPM Proxy Driver for Linux Containers +============================================= + +| Authors: +| Stefan Berger + +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 returned. If for +example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is returned. + +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. + +UAPI +==== + +.. kernel-doc:: include/uapi/linux/vtpm_proxy.h + +.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c + :functions: vtpmx_ioc_new_dev diff --git a/Documentation/tpm/tpm_vtpm_proxy.txt b/Documentation/tpm/tpm_vtpm_proxy.txt deleted file mode 100644 index 30d1902..0000000 --- a/Documentation/tpm/tpm_vtpm_proxy.txt +++ /dev/null @@ -1,71 +0,0 @@ -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. -- cgit v1.1 From 799a545bb9383c6185ad27063adca03d28ee1823 Mon Sep 17 00:00:00 2001 From: Jarkko Sakkinen Date: Thu, 3 Nov 2016 17:57:52 -0600 Subject: tpm: move documentation under Documentation/security In order too make Documentation root directory cleaner move the tpm directory under Documentation/security. Signed-off-by: Jarkko Sakkinen Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 2 +- Documentation/security/index.rst | 7 ++ Documentation/security/tpm/index.rst | 7 ++ Documentation/security/tpm/tpm_vtpm_proxy.rst | 50 ++++++++++++ Documentation/security/tpm/xen-tpmfront.txt | 113 ++++++++++++++++++++++++++ Documentation/tpm/index.rst | 7 -- Documentation/tpm/tpm_vtpm_proxy.rst | 50 ------------ Documentation/tpm/xen-tpmfront.txt | 113 -------------------------- 8 files changed, 178 insertions(+), 171 deletions(-) create mode 100644 Documentation/security/index.rst create mode 100644 Documentation/security/tpm/index.rst create mode 100644 Documentation/security/tpm/tpm_vtpm_proxy.rst create mode 100644 Documentation/security/tpm/xen-tpmfront.txt delete mode 100644 Documentation/tpm/index.rst delete mode 100644 Documentation/tpm/tpm_vtpm_proxy.rst delete mode 100644 Documentation/tpm/xen-tpmfront.txt (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index 0058b65..b4c3034 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -19,7 +19,7 @@ Contents: media/dvb-drivers/index media/v4l-drivers/index gpu/index - tpm/index + security/index Indices and tables ================== diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst new file mode 100644 index 0000000..9bae6bb --- /dev/null +++ b/Documentation/security/index.rst @@ -0,0 +1,7 @@ +====================== +Security documentation +====================== + +.. toctree:: + + tpm/index diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst new file mode 100644 index 0000000..af77a7b --- /dev/null +++ b/Documentation/security/tpm/index.rst @@ -0,0 +1,7 @@ +===================================== +Trusted Platform Module documentation +===================================== + +.. toctree:: + + tpm_vtpm_proxy diff --git a/Documentation/security/tpm/tpm_vtpm_proxy.rst b/Documentation/security/tpm/tpm_vtpm_proxy.rst new file mode 100644 index 0000000..ea08e76 --- /dev/null +++ b/Documentation/security/tpm/tpm_vtpm_proxy.rst @@ -0,0 +1,50 @@ +============================================= +Virtual TPM Proxy Driver for Linux Containers +============================================= + +| Authors: +| Stefan Berger + +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 returned. If for +example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is returned. + +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. + +UAPI +==== + +.. kernel-doc:: include/uapi/linux/vtpm_proxy.h + +.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c + :functions: vtpmx_ioc_new_dev diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.txt new file mode 100644 index 0000000..69346de --- /dev/null +++ b/Documentation/security/tpm/xen-tpmfront.txt @@ -0,0 +1,113 @@ +Virtual TPM interface for Xen + +Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) + +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 + +The goal of this work is to provide a TPM functionality to a virtual guest +operating system (in Xen terms, 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. Each guest gets its own unique, emulated, software TPM. However, each +of the vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, +which seals the secrets to the Physical TPM. If the process of creating each of +these domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends +the chain of trust rooted in the hardware TPM to virtual machines in Xen. Each +major component of vTPM is implemented as a separate domain, providing secure +separation guaranteed by the hypervisor. The vTPM domains are implemented in +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 +--------------- + +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 may be + more than one of these. + + * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver + provides vTPM access to a 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 normally 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 is also used in mini-os + domains such as pv-grub that talk to the vTPM domain. + + * 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. + + +INTEGRATION WITH XEN +-------------------- + +Support for the vTPM driver was added in Xen using the libxl toolstack in Xen +4.3. See the Xen documentation (docs/misc/vtpm.txt) for details on setting up +the vTPM and vTPM Manager stub domains. Once the stub domains are running, a +vTPM device is set up in the same manner as a disk or network device in the +domain's configuration file. + +In order to use features such as IMA that require a TPM to be loaded prior to +the initrd, the xen-tpmfront driver must be compiled in to the kernel. If not +using such features, the driver can be compiled as a module and will be loaded +as usual. diff --git a/Documentation/tpm/index.rst b/Documentation/tpm/index.rst deleted file mode 100644 index af77a7b..0000000 --- a/Documentation/tpm/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -===================================== -Trusted Platform Module documentation -===================================== - -.. toctree:: - - tpm_vtpm_proxy diff --git a/Documentation/tpm/tpm_vtpm_proxy.rst b/Documentation/tpm/tpm_vtpm_proxy.rst deleted file mode 100644 index ea08e76..0000000 --- a/Documentation/tpm/tpm_vtpm_proxy.rst +++ /dev/null @@ -1,50 +0,0 @@ -============================================= -Virtual TPM Proxy Driver for Linux Containers -============================================= - -| Authors: -| Stefan Berger - -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 returned. If for -example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is returned. - -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. - -UAPI -==== - -.. kernel-doc:: include/uapi/linux/vtpm_proxy.h - -.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c - :functions: vtpmx_ioc_new_dev diff --git a/Documentation/tpm/xen-tpmfront.txt b/Documentation/tpm/xen-tpmfront.txt deleted file mode 100644 index 69346de..0000000 --- a/Documentation/tpm/xen-tpmfront.txt +++ /dev/null @@ -1,113 +0,0 @@ -Virtual TPM interface for Xen - -Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) - -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 - -The goal of this work is to provide a TPM functionality to a virtual guest -operating system (in Xen terms, 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. Each guest gets its own unique, emulated, software TPM. However, each -of the vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, -which seals the secrets to the Physical TPM. If the process of creating each of -these domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends -the chain of trust rooted in the hardware TPM to virtual machines in Xen. Each -major component of vTPM is implemented as a separate domain, providing secure -separation guaranteed by the hypervisor. The vTPM domains are implemented in -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 ---------------- - -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 may be - more than one of these. - - * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver - provides vTPM access to a 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 normally 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 is also used in mini-os - domains such as pv-grub that talk to the vTPM domain. - - * 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. - - -INTEGRATION WITH XEN --------------------- - -Support for the vTPM driver was added in Xen using the libxl toolstack in Xen -4.3. See the Xen documentation (docs/misc/vtpm.txt) for details on setting up -the vTPM and vTPM Manager stub domains. Once the stub domains are running, a -vTPM device is set up in the same manner as a disk or network device in the -domain's configuration file. - -In order to use features such as IMA that require a TPM to be loaded prior to -the initrd, the xen-tpmfront driver must be compiled in to the kernel. If not -using such features, the driver can be compiled as a module and will be loaded -as usual. -- cgit v1.1