Table of Contents

• Description
  • This is a SIMP module
• Setup
  • What tpm2 affects
  • Beginning with tpm2
• Usage
• Limitations
• Reference
• Development
  • Acceptance tests
    • TPM2 simulator
    • Debug
    • Environment variables

Description

This module manages TPM 2.0 devices and the tpm2-tools software.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they may be submitted to our bug tracker.

This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

• When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
• If used independently, all SIMP-managed security subsystems are disabled by default and must be explicitly opted into by administrators. Please review the parameters in simp/simp_options for details.

Setup

What tpm2 affects

The tpm2 module manages:

• tpm2-software packages and services (e.g., tpm2-tools, etc.,)
• The tpm2 Facter fact
• TODO: Ownership of a TPM2 device's endorsement hierarchy

Beginning with tpm2

include 'tpm2'

Usage

To set the authentication passwords on the system:

Include the tpm module and set the following in hiera:

Note: You must indicate the desired status of all three authentications settings. If using tpm2_tools version 4 or later you can use ignore to skip any of the settings. Otherwise they must each be set to 'clear' or 'set'.

tpm2::take_ownership: true tpm2::ownership::owner: set tpm2::ownership::lock: set 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 minumum password length of 14 charaters):

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

Limitations

The tpm2_takeownership module cannot be used to change the current password. It would continually try to reset the password and would lock out the TPM. It should be used to initialized or clear the TPM only.

If the tpm2_tools are not installed it will take 2 passes to set or clear the authentication settings because it must first determine the version of tpm2_getcap installed. The tpm2::ownership modules can be use directly if you know what version of the tools will be installed. See the examples in the modules.

SIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux and compatible distributions, such as CentOS. Please see the metadata.json file for the most up-to-date list of supported operating systems, Puppet versions, and module dependencies.

Reference

See REFERENCE.md for API documentation.

Development

Please read our Contribution Guide.

Acceptance tests

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:

bundle install
bundle exec rake beaker:suites

TPM2 simulator

The acceptance tests spin up a tpm2-simulator. These simulators have been compiled and package by simp and are available in the simp-project repos, https://download.simp-project.com/simp/yum/. See the spec/acceptance/nodesets for the exact repo.

Debug

The TPM2 developers provide a debug flag. Set the environemnt variable G_MESSAGES_DEBUG=all and run tpm2-abrmd in a terminal.

Environment variables

• BEAKER_download_pre_suite_rpms When 'yes', downloads a tarball of RPMs to install before running the first Beaker suite

• BEAKER_tpm2_rpms_tarball_url

FIXME: Ensure the Acceptance tests section is correct and complete, including any module-specific instructions, and remove this message!

Please refer to the SIMP Beaker Helpers documentation for more information.