From: Jarkko Sakkinen Date: Thu, 3 Nov 2016 23:57:51 +0000 (-0600) Subject: tpm: transition tpm_vtpm_proxy documentation to the Sphinx X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=9e355ba76455d6d44f5cf888eee820ae9a06b3ec;p=GitHub%2Fmoto-9609%2Fandroid_kernel_motorola_exynos9610.git 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 --- diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc72963e87..0058b65d361c 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 000000000000..af77a7bbb070 --- /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 000000000000..ea08e76b17f5 --- /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 30d19022f869..000000000000 --- 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.