4.11.22. How to Manage a TPM Device with SIMP

This document serves as a guide to enable and use TPM devices in SIMP. Currently, both TPM 1.2 and 2.0 are supported, but only on EL7 systems.

TPM features in SIMP:

  • Taking ownership
  • Enabling a TPM-based PKCS#11 interface
  • Intel TXT and Trusted Boot
  • Enabling basic IMA measuring
    • Setting custom IMA policy (broken)

We do not support clearing ownership or measured boot at this time.

4.11.22.1. Requirements

4.11.22.1.1. General Requirements:

  • A host with a TPM 1.2 or 2.0 chip on the motherboard
  • A legacy, non-UEFI bootloader
  • A BIOS password (one should be required to enable the TPM)
  • Easy physical access to the machine to enter the BIOS password

Note

A simulated or software TPM may be used; however, it may not be able to perform all of the capabilities described.

4.11.22.1.2. Trusted Boot Hardware Requirements:

  • A CPU with Intel Trusted Execution Technology (TXT)
  • A chipset with Intel Trusted Execution Technology (TXT)

4.11.22.2. Starting with TPM

Ensure the system has a TPM. This can be done by looking for the character device /dev/tpm0, by checking the sys path manually, or by checking the tpm or tpm2 structured facts. The lack of a /dev/tpm0 device does not necessarily preclude a TPM, as a software TPM may be present.

# cat /sys/class/tpm/tpm0/device/active
1
# file /dev/tpm0
/dev/tpm0: character special (10/224)
# facter -p tpm.status
...
owned: 0,
enabled: 1,
active: 1,
...
# facter -p tpm2.tpm2_getcap.properties-variable.TPM_PT_PERSISTENT
...
ownerAuthSet => "clear",
endorsementAuthSet => "clear",
lockoutAuthSet => "clear",
reserved1 => "clear",
disableClear => "clear",
inLockout => "clear",
tpmGeneratedEPS => "set",
reserved2 => "clear"
...

4.11.22.2.1. TPM 1.2

Follow the steps below to enable and take ownership of the TPM 1.2.

  1. A BIOS password must be set to make sure no third parties can boot the host. Please set the admin password and the user password in the BIOS. If there is an option to require password at boot time, enable it. Do not enable Intel Platform Trust Technology (PTT) or Intel TXT at this time.

  2. Before a TPM can be accessed by the operating system, it must first be enabled. This has to be done in the BIOS. Refer to the documentation provided with the hardware.

  3. At this point, the SIMP TPM module can take over management of the device. Add tpm to the host’s Hiera data according to the example below or use the tpm_ownership type directly.

    classes:
  - tpm

tpm::take_ownership: true
tpm::ownership::advanced_facts: true

    Note

    The tpm_ownership type does not support clearing the TPM. The process could possibly be destructive and has been left to be a manual process.

  4. Run puppet

4.11.22.2.2. TPM 2.0

Follow the steps below to enable and take ownership of the TPM 2.0.

  1. A BIOS password must be set to make sure no third parties can boot the host. Please set the admin password and the user password in the BIOS. If there is an option to require password at boot time, enable it. Do not enable Intel Platform Trust Technology (PTT) or Intel TXT at this time.

  2. Before a TPM can be accessed by the operating system, it must first be enabled. This has to be done in the BIOS. Refer to the documentation provided with the hardware.

  3. At this point, the SIMP TPM module can take over management of the device. Add tpm2 to the host’s Hiera data according to the example below or use the tpm_ownership type directly.

    classes:
  - tpm2

tpm2::take_ownership: true
tpm2::ownership::owner: set
tpm2::ownership::lockout:  clear
tpm2::ownership::endorsement: set

    The passwords will default to automatically generated passwords using passgen. If you want to set them to specific passwords then set them in Hiera using the following settings (it expects a minimum password length of 14 characters):

    tpm2::ownership::owner_auth: 'MyOwnerPassword'
tpm2::ownership::lock_auth: 'MyLockPassword'
tpm2::ownership::endorsement_auth: 'MyEndorsePassword'

    Note

    The tpm_ownership type does not support clearing the TPM. The process could possibly be destructive and has been left to be a manual process.

  4. Run puppet

4.11.22.3. Enable Basic IMA Measuring

This section assumes the previous section is complete, the TPM in the host is owned, and it is being managed with Puppet.

IMA is a neat tool that hashes the contents of a system, and stores that hash in the TPM. IMA is a kernel-level tool, and needs a few kernel parameters and reboots to be completely set up.

Note

The default configuration of this module updates EFI boot parameters if they are present. If the system relies upon BIOS for boot, ensure there is not an EFI grub.cfg or grub2.cfg present or the BIOS grub config file will not be updated.

4.11.22.3.1. IMA Appraisal

IMA appraisal is the process that actually measures the state of the files and will stop changes to the filesystem if there is an issue detected.

  1. Make sure / and /home are mounted with the i_version option. They are created by default with these options enabled.

  2. Modify the Hiera data and add the following class:

    classes:
  - ima::appraise

  3. Run Puppet to apply the policy changes to the system; the system will be configured to reboot into ima_appraise mode fix. Reboot the system.

  4. The files on the system must now be measured and recorded. In order to do this, every file owned by root and included in the policy must be touched. This step will take some time. Puppet will provide notification not to reboot the system until the process is complete. Puppet will provide an ima_appraise_enforce_reboot notification when the process is complete.

  5. Reboot the system again to set the ima_appraise to enforce mode.

If the IMA appraisal needs to be performed again to update files after the system is in enforce mode, the following steps may be taken:

  1. Modify the Hiera data and add the following parameter:

    ima::appraise::force_fixmode: true

  2. Run Puppet to apply the policy to the system. The system will be configured to reboot into ima_appraise mode fix. Reboot the system.

  3. Run the script ima_security_attr_update.sh. The files will be measured again and the values recorded; this will again take some time.

    # /usr/local/bin/ima_security_attr_update.sh

  4. When the appraisal is complete, Puppet will provide an ima_appraise_enforce_reboot notification. Set the force_fixmode attribute in the Hiera data back to false, then run Puppet again and reboot the system.

    ima::appraise::force_fixmode: true

4.11.22.3.2. IMA Appraisal Debugging Tips and Warnings

If you reboot and are getting SELinux errors or you do not have permissions to access your files then you probably forgot to set i_version on your mounts in /etc/fstab.

If you reboot and it won’t load the initramfs then the dracut update didn’t run. You can fix this by rebooting without the ima kernel settings, running dracut -f and then rebooting in ima_appraise mode fix.

4.11.22.3.3. Managing IMA policy

This module can also support modifying which files IMA watches by editing the /sys/kernel/security/ima/policy. Reference the module source file, located at <environment path>/modules/ima/manifests/policy.pp for further details on what can and cannot be measured.

Warning

The current RedHat implementation of IMA does not seem to work after inserting our default policy (generated example in spec/files/default_ima_policy.conf). It causes the system to become read-only, even though it is only using supported configuration elements. The module will be updated soon with more sane defaults to allow for at least the minimal amount of a system to be measured. A reboot will fix the issue, but with a TPM you will have to enter the password again.

  1. Modify the Hiera data and add the following class:

    classes:
  - ima::policy

  2. Run Puppet, then reboot.

4.11.22.4. Enabling Trusted Boot (tboot) (TPM 1.2 Only)

4.11.22.4.1. General Process

The steps in the section below provide guidance and automation to perform the following:

  1. Set BIOS password
  2. Activate and own the TPM
  3. Install the tboot package and reboot into the tboot no policy kernel entry
  4. Download SINIT and put it in /boot
  5. Generate a policy and install it in the TPM NVRAM and /boot
  6. Update GRUB
  7. Reboot into a measured state

For more information about tboot in general, reference external documentation:

4.11.22.4.2. Steps

  1. Enable Intel TXT and VT-d in the BIOS.

  2. Boot into the kernel you want to trust (do not worry, this kernel will be preserved!)

  3. Follow the instructions in ‘Starting With TPM’ and ensure:

    • The TPM is owned
    • You know the owner password
    • The SRK password is ‘well-known’ (-z)

  4. Go to the Intel site and download the appropriate SINIT binary for your platform. Place this binary on a webserver, on the host itself, or in a profile module. This cannot be distributed by SIMP for licensing reasons.

  5. Add the following settings to your Hiera data for nodes that will be using Trusted Boot. It is recommended to use a hostgroup for this.

    • tpm::tboot::sinit_name - The name of the binary downloaded in the previous step
    • tpm::tboot::sinit_source - Where Puppet can find this binary
    • tpm::tboot::owner_password - The owner password

    Here is an example used for testing:

    tpm::tboot::sinit_name: 2nd_gen_i5_i7_SINIT_51.BIN
tpm::tboot::sinit_source: 'file:///root/txt/2nd_gen_i5_i7-SINIT_51/2nd_gen_i5_i7_SINIT_51.BIN'
tpm::tboot::owner_password: "%{alias('tpm::ownership::owner_pass')}"

  6. Add the tpm::tboot class to the classes array with tpm.

    • The tpm::tboot class adds two boot entries to the GRUB configuration. One should read tboot, and there should be one above it called something along the lines of tboot, no policy.
    • The Trusted Boot process requires booting into the tboot kernel before creating the policy, so we have opted to create both entries. The intermediate, no policy boot option can later be removed by setting tpm::tboot::intermediate_grub_entry to false in Hiera.

  7. Reboot into the tboot, no policy kernel entry.

  8. Puppet should run at next boot, and create the policy. Log in, ensure /boot/list.data exists. If not, run puppet again.

  9. Reboot into the tboot kernel entry.

  10. Verify that the system has completed a measured launch by running txt-stat or checking the tboot fact.

    # txt-stat
# facter -p tboot

4.11.22.4.3. Trusted Boot Debugging Tips and Warnings

  • The parse_err command will show the error code, ready to lookup in the error table included in the zip.
  • The tboot kernel option min_ram=0x2000000 (which is default) is REQUIRED on systems with more than 4GB of memory.
  • Trusted Boot measures the file required to boot into a Linux environment, and updating those file will cause a system to boot into an untrusted state. Be careful updating the kernel packages and rebuilding the initramfs (or running dracut).