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.

Reference

Table of Contents

Classes

• tpm2: Provides utilities for interacting with a TPM2 device
• tpm2::install: @summary Install tpm2 packages
• tpm2::ownership: Take ownership of a TPM device
• tpm2::ownership::changeauth: Set or clear the authentication passwords for the TPM
• tpm2::ownership::takeownership: Provides the ability to set or clear the authentication passwords for the TPM
• tpm2::service: A private class to ensure that the TABRM service is running

Resource types

• tpm2_changeauth: A type to manage ownership of a TPM 2.0. The context must be the name of the resource. It only accepts 'owner', 'lockout' and 'endorsem
• tpm2_ownership: A type to manage ownership of a TPM 2.0. Use this to set the passwords on a TPM to prevent unauthorized access. It cannot change the pa

Data types

• Tpm2::Ownership: Valid ownership options for TPM2

Classes

tpm2

Provides utilities for interacting with a TPM2 device

Parameters

The following parameters are available in the tpm2 class:

• package_ensure
• packages
• take_ownership
• tabrm_service
• tabrm_options

package_ensure

Data type: String[1]

The default ensure parameter for packages.

Default value: simplib::lookup('simp_options::package_ensure', {'default_value' => 'installed'})

packages

Data type: Hash[String[1], Hash[String[1],String[1]]]

A Hash of packages needed for tpm2-tools. The Hash format is:

<package_name>':
  ensure: <ensure_value>

Default value: simplib::lookup('tpm2::packages')

take_ownership

Data type: Boolean

Enable to allow Puppet to take ownership of the TPM

Default value: false

tabrm_service

Data type: String[1]

Systemd name of the abrmd-service

Default value: 'tpm2-abrmd'

tabrm_options

Data type: Optional[Array[String[1]]]

An unvalidated list of options to pass to $tabrm_service at start time

Default value: undef

tpm2::install

@summary Install tpm2 packages

tpm2::ownership

This class is called by setting the hiera variable tpm2::take_ownership. It will look at the tpm2 fact and determine if the tpm2-tools package has been installed and what version of the tools is installed and attempt to set or unset the authentication values for the owners, lockout and endorsement contexts.

At this time you can clear a set password but cannot change it to another value.

To use this module, set tpm2::take_ownership to true in hiera and set the parameters in hiera to override the defaults.

The passwords will default to automatically generated passwords using simplib::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::lockout_auth: 'MyLockPassword' tpm2::ownership::endorsement_auth: 'MyEndorsePassword'

Examples

In Hiera set the following:
  tpm2::take_ownership: true
  tpm2::ownership::owner: set
  tpm2::ownership::lockout:  clear
  tpm2::ownership::endorsement: set

Parameters

The following parameters are available in the tpm2::ownership class:

• owner
• endorsement
• lockout
• owner_auth
• lockout_auth
• endorsement_auth
• in_hex

owner

Data type: Enum['set','clear','ignore']

The desired state of the owner authentication. If tpm2-tools < 4.0.0 is installed you can not use the 'ignore' option. The tool needs all 3 values to work. Puppet will display a warning and not attempt to set auth value if it is used and the earlier version of tpm tools is set.

Default value: 'clear'

endorsement

Data type: Enum['set','clear','ignore']

The desired state of the endorsement authentication. See owner param for more information.

Default value: 'clear'

lockout

Data type: Enum['set','clear','ignore']

The desired state of the lockout authentication. See owner param for more information.

Default value: 'clear'

owner_auth

Data type: String[14]

The password word for owner authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_owner_auth", {'length'=> 24})

lockout_auth

Data type: String[14]

The password word for lockout authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_lock_auth", {'length'=> 24})

endorsement_auth

Data type: String[14]

The password word for endorsement authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_endorse_auth", {'length'=> 24})

in_hex

Data type: Boolean

Whether or not the passwords are in Hex. This value is ignore if tpm2_tools package > 4.0.0 is installed.

Default value: false

tpm2::ownership::changeauth

At this time you can clear a set password but cannot change it to another value.

This class works when tpm2-tools version 4.0.0 or later is installed. You can call this directly but it will not check the version of tpm2-tools installed. It will do nothing if the incorrect version is installed.

If you don't know what version of tpm2-tools will be installed then set tpm2::take_ownership to true in hiera. See the Readme for more information. Using tpm2::takeownership will require 2 puppet runs but will allow you to configure multiple machines with different tpm2-tools packages.

Examples

See the tpm2::ownership class for examples on setting it up from there.

To call directly:
 In your manifest:
   include tpm2::ownership::changeauth
 In Hiera:
   tpm2::take_ownership: false
   tpm2::ownership::changeauth::owner: 'set'

The passwords will default to automatically generated passwords using
simplib::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::changeauth::owner_auth: 'MyOwnerPassword'
  tpm2::ownership::changeauth::lockout_auth:  'MyLockPassword'
  tpm2::ownership::changeauth::endorsement_auth: 'MyEndorsePassword'

 See the man page for tpm2_changeauth for more information.

 Note: not all of the command options are currently available through the
 type.

Parameters

The following parameters are available in the tpm2::ownership::changeauth class:

• owner
• endorsement
• lockout
• owner_auth
• lockout_auth
• endorsement_auth

owner

Data type: Enum['set','clear','ignore']

The desired state of the owner authentication. Valid setting are set, clear and ignore.

Default value: 'ignore'

endorsement

Data type: Enum['set','clear','ignore']

The desired state of the endorsement authentication. Valid setting are set, clear and ignore.

Default value: 'ignore'

lockout

Data type: Enum['set','clear','ignore']

The desired state of the lockout authentication. Valid setting are set, clear and ignore.

Default value: 'ignore'

owner_auth

Data type: String[14]

The password word for owner authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_owner_auth", {'length'=> 24})

lockout_auth

Data type: String[14]

The password word for lockout authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_lock_auth", {'length'=> 24})

endorsement_auth

Data type: String[14]

The password word for endorsement authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_endorse_auth", {'length'=> 24})

tpm2::ownership::takeownership

At this time you can clear a set password but cannot change it to another value.

You can call this module directly or set tpm2::take_ownership to true in hiera. Using tpm2::takeownership will require 2 puppet runs but will allow you to configure multiple machines with different tpm2-tools packages.

You also need to set the parameters in hiera to override the defaults.

The passwords will default to automatically generated passwords using simplib::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):

If you want to clear a password you must know the current password.

tpm2::ownership::takeownership::owner_auth: 'MyOwnerPassword' tpm2::ownership::takeownership::lockout_auth: 'MyLockPassword' tpm2::ownership::takeownership::endorsement_auth: 'MyEndorsePassword'

Examples

See the Readme.md on how to use this class through the tpm2:ownership class. It can determine the version
of tpm2_tools installed and call the correct class.  If you are sure you are using tpm2_tools
you can call this module directly.

Also see the man page for tpm2_takeownership for further information.
Ih hiera:

  # Set tpm2::take_ownership to false to make sure a duplicate resource is not created.
  tpm2::take_ownership: false
  # all three values must be set to the desired state.
  tpm2::ownership::takeownership::owner: set
  tpm2::ownership::takeownership::lockout:  clear
  tpm2::ownership::takeownership::endorsement: set

Parameters

The following parameters are available in the tpm2::ownership::takeownership class:

• owner
• endorsement
• lockout
• owner_auth
• lockout_auth
• endorsement_auth
• in_hex

owner

Data type: Enum['set','clear']

The desired state of the owner authentication.

Default value: 'clear'

endorsement

Data type: Enum['set','clear']

The desired state of the endorsement authentication.

Default value: 'clear'

lockout

Data type: Enum['set','clear']

The desired state of the lockout authentication.

Default value: 'clear'

owner_auth

Data type: String[14]

The password word for owner authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_owner_auth", {'length'=> 24})

lockout_auth

Data type: String[14]

The password word for lockout authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_lock_auth", {'length'=> 24})

endorsement_auth

Data type: String[14]

The password word for endorsement authentication.

Default value: simplib::passgen("${facts['networking']['fqdn']}_tpm_endorse_auth", {'length'=> 24})

in_hex

Data type: Boolean

Whether or not the passwords are in Hex. This value is ignore if tpm2_tools package > 4.0.0 is installed.

Default value: false

tpm2::service

A private class to ensure that the TABRM service is running

Resource types

tpm2_changeauth

A type to manage ownership of a TPM 2.0.

The context must be the name of the resource. It only accepts 'owner', 'lockout' and 'endorsement' at this time.

Use this to set the passwords on a TPM to prevent unauthorized access.

It cannot change the passwords but it can clear the password

Example:

include 'tpm'

tpm2_changeauth { 'owner': auth => 'badpasswd, state => 'set' }

Properties

The following properties are available in the tpm2_changeauth type.

state

Valid values: clear, set

Whether to set the password or clear the current password. It can not change a password at this time. You must know the current password to clear the password

Parameters

The following parameters are available in the tpm2_changeauth type.

• auth
• name
• provider

auth

The authentication value for the context

name

namevar

The value of the context object to change the authorization on. Currently only handles owner, lockout, or endorsement

Default value: owner

provider

The specific backend to use for this tpm2_changeauth resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

tpm2_ownership

A type to manage ownership of a TPM 2.0.

Use this to set the passwords on a TPM to prevent unauthorized access.

It cannot change the passwords.

Example:

include 'tpm'

tpm2_ownership { 'tpm2': owner => set, lockout => set, endorsement => set, owner_auth => 'badpass', lockout_auth => 'badpass', endorsement_auth => 'badpass', }

Properties

The following properties are available in the tpm2_ownership type.

endorsement

Valid values: clear, set

Setting for owner authorization

lockout

Valid values: clear, set

Setting for owner authorization

owner

Valid values: clear, set

Setting for owner authorization

Parameters

The following parameters are available in the tpm2_ownership type.

• endorsement_auth
• in_hex
• local
• lockout_auth
• name
• owner_auth
• provider

endorsement_auth

The endorse password of the TPM

Default value: ''

in_hex

Valid values: true, false, yes, no

Whether or not the passwords are in hex

Default value: false

local

Valid values: true, false, yes, no

Whether to save the passwords on the local system

Default value: false

lockout_auth

The lock out password of the TPM

Default value: ''

name

namevar

A static name assigned to this type. You can only declare this type of resource once in your node scope

Default value: tpm2

owner_auth

The owner password of the TPM

Default value: ''

provider

The specific backend to use for this tpm2_ownership resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

Data types

Tpm2::Ownership

Valid ownership options for TPM2

Alias of Enum['set', 'clear']

• Wed Oct 11 2023 Steven Pritchard steve@sicura.us - 0.7.0

• [puppetsync] Updates for Puppet 8
  • These updates may include the following:
    • Update Gemfile
    • Add support for Puppet 8
    • Drop support for Puppet 6
    • Update module dependencies

• Wed Aug 23 2023 Steven Pritchard steve@sicura.us - 0.6.0

• Add AlmaLinux 8 support

• Mon Jun 12 2023 Chris Tessmer chris.tessmer@onyxpoint.com - 0.5.0

• Add RockyLinux 8 support

• Tue Jun 22 2021 Trevor Vaughan tvaughan@onyxpoint.com - 0.4.0

• Override systemd unit file for tpm2-abrmd for TCTI compatibility
• Fixed docs for puppet-strings

• Thu Jun 17 2021 Chris Tessmer chris.tessmer@onyxpoint.com - 0.4.0

• Removed support for Puppet 5
• Ensured support for Puppet 7 in requirements and stdlib

• Fri Jan 15 2021 Jeanne Greulich jeanne.greulich@onyxpoint.com - 0.3.2

• This change updates the tpm2 fact and tpm2::ownership to handle changes in tpm2_tools version 4. The code was updated to provide for the following changes in tpm2_tools:
  • tpm2_pcrlist was changed to tpm2_pcrread.
  • tpm2_takeownership was changed to tpm2_changeauth and its parameters and functions were changed significantly.
  • tpm2_getcap options were changed and format of the information returned was changed.
• The use of tpm2_pcrlist was replaced with tpm2_getcap since it was only used to determine if tpm2_tools package was installed.
• The version of the tools installed is derived from tpm2_getcap -v and included as part of the tpm2 fact.
• Removed requirement for fact tpm to not exist. The tpm2 fact will be populated if the tpm2 tools are installed and they can talk to the tpm. If there is a tpm fact out there from another module it will not affect this fact.
• Added a provider for the tpm2_changeauth functionality that is equivalant to what tpm2_takeownership did.
• Updated tpm2::ownership to check the version of tools installed and call the correct type and provider. The tpm2::*auth parameters will accept a value of 'ignore' if tpm2_tools version 4 or later is installed. Otherwise the parameters for tpm2::ownership have not changed.

• Wed Sep 30 2020 Trevor Vaughan tvaughan@onyxpoint.com - 0.3.1

• Fixed a bug where the tpm2_* commands could return nothing which would trigger an error in further logic.
• Fixed minor documentation issues

• Mon Feb 24 2020 Jeanne Greulich jeanne.greulich@onyxpoint.com - 0.3.0

• Added EL8 support
• Added ability to set options for abrmd service
• Removed option for managing tools. Tools can be managed or not by removing them from the package list. Note that the tools package is needed to determine the status of the TPM.

• Wed May 08 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.2.0

• Removed Puppet 4 support
• Added Puppet 6 support
• Added puppetlabs-stdlib 6 support
• Maintenance: removed OBE build/rpm_metadata/requires

• Mon Jan 07 2019 Liz Nemsick lnemsick-simp@gmail.com - 0.1.1

• Confine tpm2 fact on the presence of TPM 2 tools required for that fact evaluation
• Use simplib::passgen() in lieu of passgen(), a deprecated simplib Puppet 3 function.
• Update the upper bound of stdlib to < 6.0.0
• Update a URL in the README.md

• Wed Nov 21 2018 Adam Yohrling adam.yohrling@onyxpoint.com - 0.1.0

• Added OEL support

• Mon Nov 05 2018 Liz Nemsick lnemsick-simp@gmail.com - 0.1.0

• Update to Hiera 5

• Mon Jul 30 2018 Jeanne Greulich jeanne.greulich@onyxpoint.com - 0.1.0

• added take ownership

• Mon Jul 23 2018 Chris Tessmer chris.tessemr@onyxpoint.com - 0.1.0

• initial module