[[PageOutline]]

= Trusted Protection Module

A Trusted Platform Module (TPM) is a small piece of hardware designed to provide various security functionalities. It offers numerous features, such as storing secrets, ‘measuring’ boot, and may act as an external cryptographic engine.

[https://trustedcomputinggroup.org/ The Trusted Computing Group (TCG)] delivers a document called TPM Interface Specifications (TIS) which describes the architecture of such devices and how they are supposed to behave as well as various details around the concepts. Additionally they provide a Library Specification.

TPM chips are either compliant with the initial specification or the v2.0+ specification: See [https://en.wikipedia.org/wiki/Trusted_Platform_Module#TPM_1.2_vs_TPM_2.0 TPM v1.2 vs TPM 2.0] for details.

Please also read: [wiki:venice/secure_boot Gateworks TPM Wiki when used with Secure Boot]

== Microchip ATTPM20P
Gateworks has an optional TPM on the Venice and Malibu family SBCs:
 * Malibu GW8901
 * Venice:
  * GW74xx (revision B+)
  * GW73xx (revision F+) 
  * GW72xx (revision F+) 
  * GW71xx (revision E+)

The TPM used is a Microchip ATTPM20P-H6MA1-10 TPM connected to the SPI bus and is compliant to the Trusted Computing Group (TCG) [https://trustedcomputinggroup.org/ Trusted Platform Module (TPM) Version 2.0]

This provides cryptographic support for:
 - HMAC
 - AES-128
 - SHA-1
 - SHA-256
 - ECC BN_P256, ECCNIST_P256
 - RSA 1024-2048 bit keys

== Linux Driver
The TIS compliant TPM devices are supported by the TCG SPI Linux driver:
 * drivers/char/tpm/ (CONFIG_TCG_TIS_CORE, CONFIG_TCG_TIS, CONFIG_TCG_TIS_SPI)

This driver provides access via:
 - /dev/tpm0
 - /dev/tpmrm0

A solid [https://github.com/tpm2-software TPM 2.0 software stack is available for Linux]:
 - [https://github.com/tpm2-software/tpm2-tss tpm2-tss] TPM Software Stack (tss) 
 - [https://github.com/tpm2-software/tpm2-tools tpm2-tools] TPM2 tools based on the tpm2-tss stack
 - [https://github.com/tpm2-software/tpm2-abrmd tpm2-abrmd] TPM2 Access Broker and Resource Manager

Examples:
 - Install packages
{{{#!bash
apt install tpm2-tools tpm2-abrmd
}}}
 - Show tpm capabilities/properties:
{{{#!bash
root@jammy-malibu:~# tpm2_getcap properties-fixed
TPM2_PT_FAMILY_INDICATOR:
  raw: 0x322E3000
  value: "2.0"
TPM2_PT_LEVEL:
  raw: 0
TPM2_PT_REVISION:
  raw: 0x77
  value: 1.19
TPM2_PT_DAY_OF_YEAR:
  raw: 0x42
TPM2_PT_YEAR:
  raw: 0x7DE
TPM2_PT_MANUFACTURER:
  raw: 0x4D434850
  value: "MCHP"
TPM2_PT_VENDOR_STRING_1:
  raw: 0x0
  value: ""
  .....
}}}
 - Read the PCR Values:
{{{#!bash
root@jammy-venice:~# tpm2_pcrread
  sha1:
    0 : 0x0000000000000000000000000000000000000000
    1 : 0x0000000000000000000000000000000000000000
    2 : 0x0000000000000000000000000000000000000000
    3 : 0x0000000000000000000000000000000000000000
    4 : 0x0000000000000000000000000000000000000000
    5 : 0x0000000000000000000000000000000000000000
    6 : 0x0000000000000000000000000000000000000000
    7 : 0x0000000000000000000000000000000000000000
    8 : 0x0000000000000000000000000000000000000000
    9 : 0x0000000000000000000000000000000000000000
    10: 0x0000000000000000000000000000000000000000
    11: 0x0000000000000000000000000000000000000000
    12: 0x0000000000000000000000000000000000000000
    13: 0x0000000000000000000000000000000000000000
    14: 0x0000000000000000000000000000000000000000
    15: 0x0000000000000000000000000000000000000000
    16: 0x0000000000000000000000000000000000000000
    17: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
    18: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
    19: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
    20: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
    21: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
    22: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
    23: 0x0000000000000000000000000000000000000000
  sha256:
}}}
 - Clearing the TPM
{{{#!bash
tpm2_clear
}}}
 - Generate Random Number
{{{#!bash
tpm2_getrandom --hex 8
}}}

Please also read: [wiki:venice/secure_boot Gateworks TPM Wiki when used with Secure Boot]

== PCR Values
A cryptographic hash (sometimes called a 'digest') is a kind of 'signature' for a set of data. For example the SHA-256 algorithm can be used to generate an almost-unique 256-bit (32-byte) signature (aka 'hash' or 'digest') for a file. Note that this signature/hash/digest is not 'encryption' - it is a one way cryptographic function and is a fixed size for any source of data.

Starting from a root of trust (typically the SoC BOOT ROM) each software stage during the boot process is supposed to to some measurements and store them in a safe place. A 'measure' is just a signature/hash/digest of a memory region. This value can be sent to the TPM as a measure which will merge with measurement with the previous ones.

The hardware feature used to store and merge these measurements is called Platform Configuration Registers (PCR). At power-up a PCR is set to a known value (typically either 0x00's or 0xff's) and sending a new value to the TPM is called 'extending a PCR' because the chosen register will extend its value with the one received. This way a PCR can only evolve in one direction and never go back unless the platform is reset. Each software stage will be in charge of extending a set of PCRs with digests of the next software stage. Once in Linux for example user software may ask the TPM to deliver its secrects but the only way to get them is having all PCRs matching a known pattern which can only be obtained by extending the PCRs in the right order with the right digets.

If the stored PCR values in the TPM do not match the currently booting system PCRs, access will not be granted. For example, someone trying to boot a Ubuntu Live CD would not be able to access the TPM key as the PCRs generated from the original disk and stored in the TPM will not match the newly generated PCRs from the boot CD. PCRs use hashing and thus any new value is concatenated with the old and then hashed. This new hash will replace the old hash. The definition of each specific PCR register can be found online.   

Please also read: [wiki:venice/secure_boot Gateworks TPM Wiki when used with Secure Boot]

== TPM Key Flow
A general flow for loading a key into the TPM: (arguments needed for below commands specific to each application )
{{{#!bash
tpm2_createpolicy  # Create PCR Policy
tpm2_createprimary  # Create primary TPM object
tpm2_create  # Create TPM Object with Secret
tpm2_load  # Load object into the TPM
tpm2_evictcontrol  # Make TPM Object Persistant
rm files #remove your working files
}}}

Please also read: [wiki:venice/secure_boot Gateworks TPM Wiki when used with Secure Boot]

== U-Boot
U-Boot has TPM support as well:
 * drivers/tpm/tpm2_tis_spi.c (CONFIG_TPM,CONFIG_TPM2_TIS_SPI)

Usage Example:
{{{#!bash
u-boot=> tpm device
device 0: tpm@0 v2.0: VendorID 0x1114, DeviceID 0x3205, RevisionID 0x01 [open]
u-boot=> tpm info
tpm@0 v2.0: VendorID 0x1114, DeviceID 0x3205, RevisionID 0x01 [open]
u-boot=> tpm init
u-boot=> tpm startup TPM2_SU_CLEAR
u-boot=> tpm self_test full                  
u-boot=> tpm self_test continue
}}}

At this point you can pursue [https://bootlin.com/blog/measured-boot-with-a-tpm-2-0-in-u-boot/ measured boot] byt extending the PCR as needed:
{{{#!bash
u-boot=> tpm extend 0 $loadaddr # extend PCR 0 using digest loaded to $loadaddr
}}}

Please also read: [wiki:venice/secure_boot Gateworks TPM Wiki when used with Secure Boot]

Seee also:
 - [https://lwn.net/Articles/571031/ Verified U-Boot]
 - [https://bootlin.com/blog/measured-boot-with-a-tpm-2-0-in-u-boot/ Measured boot with a TPM 2.0 in U-Boot]

== Additional Resources
 * Gateworks Venice Secure Boot Wiki:  [wiki:venice/secure_boot Gateworks TPM Wiki when used with Secure Boot] 
 * Security Considerations for Embedded Designs: https://www.gateworks.com/security-considerations-for-embedded-designs-single-board-computers/
 * TPM Specification: https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/
 * Microchip TPM Product Page: https://www.microchip.com/en-us/product/attpm20p
 * The Web - A lot of examples and information about TPMs are available by searching the web