TPM documentation updates
Subsystems (2)
Jarkko Sakkinen
maintainercover TPM documentation updates
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.
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
Signature · 1 line
2.44.0
Jarkko Sakkinen
maintainerPATCH 1/2 MAINTAINERS: Update URL's for KEYS/KEYRINGS_INTEGRITY and TPM DEVICE DRIVER
Add TPM driver test suite URL to the MAINTAINERS files and move the wiki URL to more appropriate location.
---
v2:
- Typo fix: https://lore.kernel.org/all/eaa5107ac4f982b6fd6e80b522643a591e719dc9.camel@HansenPartnership.com/
- Typo fix: https://lore.kernel.org/all/[email protected]/
--- MAINTAINERS | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
MAINTAINERS +2 -1
@@ -12015,6 +12015,7 @@ M: Mimi Zohar <[email protected]> L: [email protected] L: [email protected] 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 <[email protected]> R: Jason Gunthorpe <[email protected]> L: [email protected] 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/
Signature · 1 line
2.44.0
Jarkko Sakkinen
maintainerPATCH 2/2 Documentation: tpm_tis
In reply to Jarkko SakkinenBased 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.
---
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/[email protected]/
v2:
- Fixed errors reported by Randy:
https://lore.kernel.org/all/[email protected]/
- 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
Documentation/security/tpm/index.rst +1 -0
@@ -5,6 +5,7 @@ Trusted Platform Module documentation .. toctree:: tpm_event_log + tpm_tis tpm_vtpm_proxy xen-tpmfront tpm_ftpm_tee
Documentation/security/tpm/tpm_tis.rst new file +46 -0
46 lines not on this page · raw message
Signature · 1 line
2.44.0
Re: [PATCH 2/2] Documentation: tpm_tis
Quoted 12 lines · Jarkko Sakkinen
Documentation/security/tpm/tpm_tis.rst new file +6
-0@@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +TPM FIFO interface driver +========================= +
Documentation/security/tpm/tpm_tis.rst line 16
Quoted 10 lines
Documentation/security/tpm/tpm_tis.rst new file +10
-0+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 ..."?
Quoted 20 lines
Documentation/security/tpm/tpm_tis.rst new file +20
-0+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.
Documentation/security/tpm/tpm_tis.rst line 46
Quoted 10 lines
Documentation/security/tpm/tpm_tis.rst new file +10
-0+- 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,
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Jarkko Sakkinen
maintainerRe: [PATCH 2/2] Documentation: tpm_tis
Quoted 16 lines · Bagas Sanjaya
Quoted 15 lines · Jarkko Sakkinen
Documentation/security/tpm/tpm_tis.rst new file +9
-0@@ -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.
Quoted 8 lines
Documentation/security/tpm/tpm_tis.rst line 16
Quoted 7 lines
Documentation/security/tpm/tpm_tis.rst new file +7
-0+ +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 theDid you mean "For historical reasons above ..."?
That would be better wording.
Quoted 33 lines
Quoted 20 lines
Documentation/security/tpm/tpm_tis.rst new file +20
-0+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.Documentation/security/tpm/tpm_tis.rst line 46
Quoted 10 lines
Documentation/security/tpm/tpm_tis.rst new file +10
-0+- 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,
Quoted 1 line
Reviewed-by Bagas Sanjaya <[email protected]>
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