[PATCH 0/2] TPM documentation updates

[PATCH 0/2] TPM documentation updates

[Jarkko Sakkinen]

Re-send of TPM documentation updates. Note that in this patch set the
patch versions do not have relation to the patch set version, as they
were before managed as independent patches.

Cc: Alexander Steffen <Alexander.Steffen@infineon.com>
CC: Daniel P. Smith <dpsmith@apertussolutions.com>
Cc: James Bottomley <James.Bottomley@HansenPartnership.com>
Cc: Jason Gunthorpe <jgg@ziepe.ca>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Lino Sanfilippo <l.sanfilippo@kunbus.com>
Cc: Mimi Zohar <zohar@linux.ibm.com>
Cc: Peter Huewe <peterhuewe@gmx.de>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: linux-integrity@vger.kernel.org

v1:
- Collect the latest versions of patches sent earlier.

Jarkko Sakkinen (2):
  MAINTAINERS: Update URL's for KEYS/KEYRINGS_INTEGRITY and TPM DEVICE
    DRIVER
  Documentation: tpm_tis

 Documentation/security/tpm/index.rst   |  1 +
 Documentation/security/tpm/tpm_tis.rst | 46 ++++++++++++++++++++++++++
 MAINTAINERS                            |  3 +-
 3 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/security/tpm/tpm_tis.rst

-- 
2.44.0

[PATCH 1/2] MAINTAINERS: Update URL's for KEYS/KEYRINGS_INTEGRITY and TPM DEVICE DRIVER

[Jarkko Sakkinen]

Add TPM driver test suite URL to the MAINTAINERS files and move the wiki
URL to more appropriate location.

Link: https://gitlab.com/jarkkojs/linux-tpmdd-test
Link: https://kernsec.org/wiki/index.php/Linux_Kernel_Integrity
Acked-by: Paul Menzel <pmenzel@molgen.mpg.de>
Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org>
---
v2:
- Typo fix: https://lore.kernel.org/all/eaa5107ac4f982b6fd6e80b522643a591e719dc9.camel@HansenPartnership.com/
- Typo fix: https://lore.kernel.org/all/1ab10318-5e3d-417c-9984-7b17f4e386e3@molgen.mpg.de/
---
 MAINTAINERS | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 1339918df52a..01dc4940fc06 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12015,6 +12015,7 @@ M:	Mimi Zohar <zohar@linux.ibm.com>
 L:	linux-integrity@vger.kernel.org
 L:	keyrings@vger.kernel.org
 S:	Supported
+W:	https://kernsec.org/wiki/index.php/Linux_Kernel_Integrity
 F:	security/integrity/platform_certs
 
 KFENCE
@@ -22344,7 +22345,7 @@ M:	Jarkko Sakkinen <jarkko@kernel.org>
 R:	Jason Gunthorpe <jgg@ziepe.ca>
 L:	linux-integrity@vger.kernel.org
 S:	Maintained
-W:	https://kernsec.org/wiki/index.php/Linux_Kernel_Integrity
+W:	https://gitlab.com/jarkkojs/linux-tpmdd-test
 Q:	https://patchwork.kernel.org/project/linux-integrity/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/jarkko/linux-tpmdd.git
 F:	drivers/char/tpm/
-- 
2.44.0

[PATCH 2/2] Documentation: tpm_tis

[Jarkko Sakkinen]

Based recent discussions on LKML, provide preliminary bits of tpm_tis_core
dependent drivers. Includes only bare essentials but can be extended later
on case by case. This way some people may even want to read it later on.

Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org>
---
v4:
- Extended the text to address some of Stefan's concerns with v2.
- Had to unfortunately remove Randy's reviewed-by because of this, given
  the amount of text added.
v3:
- Fixed incorrect buffer size:
  https://lore.kernel.org/linux-integrity/d957dbd3-4975-48d7-abc5-1a01c0959ea3@linux.ibm.com/
v2:
- Fixed errors reported by Randy:
  https://lore.kernel.org/all/aed28265-d677-491a-a045-24b351854b24@infradead.org/
- Improved the text a bit to have a better presentation.
---
 Documentation/security/tpm/index.rst   |  1 +
 Documentation/security/tpm/tpm_tis.rst | 46 ++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 Documentation/security/tpm/tpm_tis.rst

diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
index fc40e9f23c85..f27a17f60a96 100644
--- a/Documentation/security/tpm/index.rst
+++ b/Documentation/security/tpm/index.rst
@@ -5,6 +5,7 @@ Trusted Platform Module documentation
 .. toctree::
 
    tpm_event_log
+   tpm_tis
    tpm_vtpm_proxy
    xen-tpmfront
    tpm_ftpm_tee
diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
new file mode 100644
index 000000000000..b448ea3db71d
--- /dev/null
+++ b/Documentation/security/tpm/tpm_tis.rst
@@ -0,0 +1,46 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
+TPM FIFO interface driver
+=========================
+
+TCG PTP Specification defines two interface types: FIFO and CRB. The former is
+based on sequenced read and write operations,  and the latter is based on a
+buffer containing the full command or response.
+
+FIFO (First-In-First-Out) interface is used by the tpm_tis_core dependent
+drivers. Originally Linux had only a driver called tpm_tis, which covered
+memory mapped (aka MMIO) interface but it was later on extended to cover other
+physical interfaces supported by the TCG standard.
+
+For legacy compliance the original MMIO driver is called tpm_tis and the
+framework for FIFO drivers is named as tpm_tis_core. The postfix "tis" in
+tpm_tis comes from the TPM Interface Specification, which is the hardware
+interface specification for TPM 1.x chips.
+
+Communication is based on a 20 KiB buffer shared by the TPM chip through a
+hardware bus or memory map, depending on the physical wiring. The buffer is
+further split into five equal-size 4 KiB buffers, which provide equivalent
+sets of registers for communication between the CPU and TPM. These
+communication endpoints are called localities in the TCG terminology.
+
+When the kernel wants to send commands to the TPM chip, it first reserves
+locality 0 by setting the requestUse bit in the TPM_ACCESS register. The bit is
+cleared by the chip when the access is granted. Once it completes its
+communication, the kernel writes the TPM_ACCESS.activeLocality bit. This
+informs the chip that the locality has been relinquished.
+
+Pending localities are served in order by the chip in descending order, one at
+a time:
+
+- Locality 0 has the lowest priority.
+- Locality 5 has the highest priority.
+
+Further information on the purpose and meaning of the localities can be found
+in section 3.2 of the TCG PC Client Platform TPM Profile Specification.
+
+References
+==========
+
+TCG PC Client Platform TPM Profile (PTP) Specification
+https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/
-- 
2.44.0

Re: [PATCH 2/2] Documentation: tpm_tis

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2748 bytes --]

On Tue, Apr 09, 2024 at 10:08:47PM +0300, Jarkko Sakkinen wrote:
> diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
> new file mode 100644
> index 000000000000..b448ea3db71d
> --- /dev/null
> +++ b/Documentation/security/tpm/tpm_tis.rst
> @@ -0,0 +1,46 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=========================
> +TPM FIFO interface driver
> +=========================
> +
> +TCG PTP Specification defines two interface types: FIFO and CRB. The former is
> +based on sequenced read and write operations,  and the latter is based on a
> +buffer containing the full command or response.
> +
> +FIFO (First-In-First-Out) interface is used by the tpm_tis_core dependent
> +drivers. Originally Linux had only a driver called tpm_tis, which covered
> +memory mapped (aka MMIO) interface but it was later on extended to cover other
> +physical interfaces supported by the TCG standard.
> +
> +For legacy compliance the original MMIO driver is called tpm_tis and the
Did you mean "For historical reasons above ..."?
> +framework for FIFO drivers is named as tpm_tis_core. The postfix "tis" in
> +tpm_tis comes from the TPM Interface Specification, which is the hardware
> +interface specification for TPM 1.x chips.
> +
> +Communication is based on a 20 KiB buffer shared by the TPM chip through a
> +hardware bus or memory map, depending on the physical wiring. The buffer is
> +further split into five equal-size 4 KiB buffers, which provide equivalent
> +sets of registers for communication between the CPU and TPM. These
> +communication endpoints are called localities in the TCG terminology.
> +
> +When the kernel wants to send commands to the TPM chip, it first reserves
> +locality 0 by setting the requestUse bit in the TPM_ACCESS register. The bit is
> +cleared by the chip when the access is granted. Once it completes its
> +communication, the kernel writes the TPM_ACCESS.activeLocality bit. This
> +informs the chip that the locality has been relinquished.
> +
> +Pending localities are served in order by the chip in descending order, one at
> +a time:
> +
> +- Locality 0 has the lowest priority.
> +- Locality 5 has the highest priority.
> +
> +Further information on the purpose and meaning of the localities can be found
> +in section 3.2 of the TCG PC Client Platform TPM Profile Specification.
> +
> +References
> +==========
> +
> +TCG PC Client Platform TPM Profile (PTP) Specification
> +https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/

Other than that,

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 2/2] Documentation: tpm_tis

[Jarkko Sakkinen]

On Thu Apr 11, 2024 at 1:50 PM EEST, Bagas Sanjaya wrote:
> On Tue, Apr 09, 2024 at 10:08:47PM +0300, Jarkko Sakkinen wrote:
> > diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
> > new file mode 100644
> > index 000000000000..b448ea3db71d
> > --- /dev/null
> > +++ b/Documentation/security/tpm/tpm_tis.rst
> > @@ -0,0 +1,46 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=========================
> > +TPM FIFO interface driver
> > +=========================
> > +
> > +TCG PTP Specification defines two interface types: FIFO and CRB. The former is
> > +based on sequenced read and write operations,  and the latter is based on a
> > +buffer containing the full command or response.
> > +
> > +FIFO (First-In-First-Out) interface is used by the tpm_tis_core dependent
> > +drivers. Originally Linux had only a driver called tpm_tis, which covered
> > +memory mapped (aka MMIO) interface but it was later on extended to cover other
> > +physical interfaces supported by the TCG standard.
> > +
> > +For legacy compliance the original MMIO driver is called tpm_tis and the
> Did you mean "For historical reasons above ..."?

That would be better wording.

> > +framework for FIFO drivers is named as tpm_tis_core. The postfix "tis" in
> > +tpm_tis comes from the TPM Interface Specification, which is the hardware
> > +interface specification for TPM 1.x chips.
> > +
> > +Communication is based on a 20 KiB buffer shared by the TPM chip through a
> > +hardware bus or memory map, depending on the physical wiring. The buffer is
> > +further split into five equal-size 4 KiB buffers, which provide equivalent
> > +sets of registers for communication between the CPU and TPM. These
> > +communication endpoints are called localities in the TCG terminology.
> > +
> > +When the kernel wants to send commands to the TPM chip, it first reserves
> > +locality 0 by setting the requestUse bit in the TPM_ACCESS register. The bit is
> > +cleared by the chip when the access is granted. Once it completes its
> > +communication, the kernel writes the TPM_ACCESS.activeLocality bit. This
> > +informs the chip that the locality has been relinquished.
> > +
> > +Pending localities are served in order by the chip in descending order, one at
> > +a time:
> > +
> > +- Locality 0 has the lowest priority.
> > +- Locality 5 has the highest priority.
> > +
> > +Further information on the purpose and meaning of the localities can be found
> > +in section 3.2 of the TCG PC Client Platform TPM Profile Specification.
> > +
> > +References
> > +==========
> > +
> > +TCG PC Client Platform TPM Profile (PTP) Specification
> > +https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/
>
> Other than that,
>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>


Thanks! I'll apply this with the fix you proposed.

For everyone: this is by no means perfect. The point is to seed
something we can build on top of. So I leave it rather lacking stuff
than try to document every possible bells and whistle. This can be
then improved based on discussions and future patch sets.

BR, Jarkko