4.11.27. 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 TPM 2.0 features are only available on EL7 systems.
TPM features in SIMP:
SIMP does not support clearing ownership or measured boot at this time.
4.11.27.1. Requirements¶
4.11.27.1.1. General Requirements:¶
- A host with a TPM 1.2 or 2.0 chip on the motherboard
- Tools to manage TPM hardware, namely tpm-tools or tpm2-tools
- 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.27.1.2. Trusted Boot Hardware Requirements:¶
- A CPU with Intel Trusted Execution Technology (TXT)
- A chipset with Intel Trusted Execution Technology (TXT)
4.11.27.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, using tools provided
to manage and utilize TPM hardware, 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.
Note
The
tpm
andtpm2
structured facts are included in the SIMPtpm
andtpm2
classes and rely upon functionality provided by thetpm-tools
andtpm2-tools
RPMs, respectively. The RPM packages are automatically installed if the classes are included and a TPM is detected by Puppet. To manually install these RPMs, enter the following commands with root permissions, either via sudo or running as root:# yum install tpm-tools # yum install tpm2-tools
The commands and sample outputs for successful tests verifying a TPM is present include:
# 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" ... # tpm_version TPM 1.2 Version Info: Chip Version: 1.2.18.160 Spec Level: 2 ... # tpm2_getcap --capability="properties-fixed" TPM_PT_FAMILY_INDICATOR: as UINT32: 0x08322e3000 as string: "2.0" TPM_PT_LEVEL: 0 TPM_PT_REVISION: 1.49 ...
4.11.27.3. TPM Simulators¶
The SIMP TPM 1.2 and TPM 2.0 simulator RPMs are packages containing compiled versions of IBM’s Software TPM 1.2 and IBM’s Software TPM 2.0. The RPMs can be regenerated by downloading the code from their respective project repositories, SIMP TPM 1.2 Simulator and SIMP TPM 2.0 Simulator. After installing the RPMs, the TPMs can be initialized.
Note
Root permission, either via sudo or running as root, is necessary to install and initialize the TPM simulators.
4.11.27.3.1. Installing and Initializing the TPM 1.2 Simulator¶
The TPM 1.2 simulator RPM is included with the SIMP repositories and can be installed via yum with the command:
# yum install simp-tpm12-simulator
To initialize the TPM 1.2 simulator on EL6, issue the following commands:
# service tpm12-simulator start # service tpm12-tpmbios start # service tpm12-simulator restart # service tpm12-tpmbios start # service tpm12-tpminit start # service tpm12-tcsd start
To initialize the TPM 1.2 simulator on EL7, issue the following commands:
# systemctl start tpm12-simulator # systemctl start tpm12-tpmbios # systemctl restart tpm12-simulator # systemctl start tpm12-tpmbios # systemctl start tpm12-tpminit # systemctl start tpm12-tcsd
The tpm_version
command, provided by the tpm-tools
RPM, can be used to
verify the TPM 1.2 simulator has been initialized.
# tpm_version
4.11.27.3.2. Installing and Initializing the TPM 2.0 Simulator¶
The TPM 2.0 simulator RPM (EL7 only) is included with the SIMP repositories and can be installed via yum with the command:
# yum install simp-tpm2-simulator
To initialize the TPM 2.0 simulator, issue the following commands:
# runuser tpm2sim --shell /bin/sh -c "cd /tmp; nohup \ /usr/local/bin/tpm2-simulator &> /tmp/tpm2-simulator.log &" # mkdir -p /etc/systemd/system/tpm2-abrmd.service.d # printf "[Service]\nExecStart=\nExecStart=/sbin/tpm2-abrmd -t socket" \ > /etc/systemd/system/tpm2-abrmd.service.d/override.conf # systemctl daemon-reload # systemctl start tpm2-abrmd
The tpm2_getcap
command, provided by tpm2-tools RPM, can be used to verify
the TPM 2.0 simulator has been initialized:
# tpm2_getcap --capability="properties-fixed"
4.11.27.3.3. TPM 1.2 Management¶
Follow the steps below to enable and take ownership of the TPM 1.2.
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.
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.
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 thetpm_ownership
type directly.simp::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.Run puppet
4.11.27.3.4. TPM 2.0 Management¶
Follow the steps below to enable and take ownership of the TPM 2.0.
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.
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.
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 thetpm_ownership
type directly.simp::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
simp::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.Run puppet
4.11.27.4. 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.27.4.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.
Make sure
/
and/home
are mounted with thei_version option
. They are created by default with these options enabled.Modify the Hiera data and add the following class:
simp::classes: - ima::appraise
Run Puppet to apply the policy changes to the system; the system will be configured to reboot into
ima_appraise
modefix
. Reboot the system.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.Reboot the system again to set the
ima_appraise
toenforce
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:
Modify the Hiera data and add the following parameter:
ima::appraise::force_fixmode: true
Run Puppet to apply the policy to the system. The system will be configured to reboot into
ima_appraise
modefix
. Reboot the system.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
When the appraisal is complete, Puppet will provide an
ima_appraise_enforce_reboot
notification. Set theforce_fixmode
attribute in the Hiera data back tofalse
, then run Puppet again and reboot the system.ima::appraise::force_fixmode: true
4.11.27.4.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.27.4.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.
Modify the Hiera data and add the following class:
simp::classes: - ima::policy
Run Puppet, then reboot.
4.11.27.5. Enabling Trusted Boot (tboot) (TPM 1.2 Only)¶
4.11.27.5.1. General Process¶
The steps in the section below provide guidance and automation to perform the following:
- Set BIOS password
- Activate and own the TPM
- Install the
tboot
package and reboot into thetboot no policy
kernel entry - Download SINIT and put it in
/boot
- Generate a policy and install it in the TPM NVRAM and
/boot
- Update GRUB
- Reboot into a measured state
For more information about tboot
in general, see:
4.11.27.5.2. Steps¶
Enable Intel
TXT
andVT-d
in the BIOS.Boot into the kernel you want to trust (do not worry, this kernel will be preserved!)
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
)
Go to the Intel site and download the appropriate SINIT binary for your platform. Place this binary on a web server, on the host itself, or in a profile module. This cannot be distributed by SIMP for licensing reasons.
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 steptpm::tboot::sinit_source
- Where Puppet can find this binarytpm::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')}"
Add the
tpm::tboot
class to the classes array withtpm
.- The
tpm::tboot
class adds two boot entries to the GRUB configuration. One should readtboot
, and there should be one above it called something along the lines oftboot, 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 settingtpm::tboot::intermediate_grub_entry
tofalse
in Hiera.
- The
Reboot into the
tboot, no policy
kernel entry.Puppet should run at next boot, and create the policy. Log in, ensure
/boot/list.data
exists. If not, run puppet again.Reboot into the
tboot
kernel entry.Verify that the system has completed a measured launch by running
txt-stat
or checking thetboot
fact.# txt-stat # facter -p tboot
4.11.27.5.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 optionmin_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 files will cause a system to boot into an untrusted state.
Be careful updating the
kernel
packages and rebuilding theinitramfs
(or runningdracut
).
4.11.27.6. HIRS¶
The simp-hirs_provisioner
module installs and configures the HIRS
TPM provisioner on specified systems. An Attestation Certificate Authority (ACA)
must be set up independently. Details of how to do this are provided on the
HIRS website. Additionally, the acceptance tests in the SIMP
hirs_provisioner module include an example of how to do so.
To install and configure the HIRS TPM Provisioner, add the following Hiera:
simp::classes: - hirs_provisioner hirs_provisioner::config::aca_fqdn: 'aca.fullyqualified.domain'