tpm

partner

manages TPMs and IMA (if your system supports it)

Project URL RSS Feed Report issues

Module Stats

14,144 downloads

87 latest version

4.6 quality score

Version information

released Sep 29th 2016

This version is compatible with:

CentOS
,
RedHat

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'simp-tpm', '0.1.0'

Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add simp-tpm

Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install simp-tpm --version 0.1.0

Tags: simp, tpm, pkcs11, txt, intel, tboot

Documentation

simp/tpm — version 0.1.0 Sep 29th 2016

Description
Setup - The basics of getting started with tpm
Usage - Configuration options and additional functionality
Reference - An under-the-hood peek at what the module is doing and how
Limitations - OS compatibility, etc.
Development - Guide for contributing to the module
- Acceptance Tests - Beaker env variables

Description

This module manages a TPM, including taking ownership and enabling IMA. You must take ownership of a TPM to load and unload certs, use it as a PKCS #11 interface, or to use SecureBoot or IMA.

The Integrity Management Architecture (IMA) subsystem is a tool that uses the TPM to verify integrity of the system, based on filesystem and file hashes. The IMA class sets up IMA kernel boot flags if they are not enabled and when they are, mounts the securityfs.

The TPM ecosystem has been designed to be difficult to automate. The difficulty has shown many downsides of using a tool like this module to manage your TPM device. For example, simply reading the TPM's public key after taking ownership of the device requires the owner password to be typed in at the command line. This is an intentional feature to encourage admins to be physically present at the machine with the device. To get around this, the provider included in this module and the advanced facts use Ruby's expect library to interact with the command line. This module also drops the owner password in the Puppet $vardir to make interacting with trousers in facts possible.

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 $client_nets, $enable_* and $use_* parameters in manifests/init.pp for details.

Setup

What tpm affects

WARNING

This module can take ownership of your TPM. This could be a destructive process and is not easily reversed. For that reason, the provider does not support clearing a TPM.

This module will:

install tpm-tools and trousers
enable the tcsd service
(OPTIONAL) Take ownership of the TPM
- The password will be in a flat file in $vardir/simp
(OPTIONAL) Enable IMA on the host

Setup Requirements

In order to use the TPM module or a TPM in general, you must do the following:

Enable the TPM in BIOS
Set a user/admin BIOS password
Be able to type in the user/admin password at boot time, every boot

Beginning with the TPM module

Include the TPM class and set the passwords in hieradata:

classes:
  - tpm

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

To enable IMA, add this line to hiera:

tpm::use_ima: true

Usage

The type and provider provided in this module can be used as follows:

tpm_ownership { 'tpm0':
  ensure         => present,
  owner_pass     => 'badpass',
  srk_pass       => 'badpass2',
  advanced_facts => true
}

Reference

Please refer to the inline documentation within each source file, or to the module's generated YARD documentation for reference material.

Limitations

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.

This module does not support clearing a previously owned TPM.

Development

Please read our Contribution Guide and visit our developer wiki.

Acceptance tests

TODO: There are currently no acceptance tests. We would need to use a virtual TPM to ensure test system stability, and it requires quite a few patches to libvirt, associated emulation software, Beaker, and Vagrant before acceptance tests for this module become feasible. Read our progress so far on the issue.

This module will include Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests will 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, when written, run the following:

bundle install
bundle exec rake beaker:suites

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

Types in this module release

tpm_ownership

A type to manage ownership of a TPM. owner_pass and srk_pass are required.

Example:

include 'tpm'

tpm_ownership { 'tpm0': ensure => present, owner_pass => 'badpass', srk_pass => 'badpass2' }

Parameters
advanced_facts	Enabling the advanced facts will write your owner password to a file on the system, only readable by the root user. It will be used to query the TPM using trousers.
ensure
name	The name of the resource - usually tpm0, the default device.
owner_pass	The owner password of the TPM
provider
srk_pass	The SRK password of the TPM

Providers
trousers

pupmod-simp-tpm - A Puppet Module for managing the TPM

--

Per Section 105 of the Copyright Act of 1976, these works are not entitled to
domestic copyright protection under US Federal law.

The US Government retains the right to pursue copyright protections outside of
the United States.

The United States Government has unlimited rights in this software and all
derivatives thereof, pursuant to the contracts under which it was developed and
the License under which it falls.

---

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

tpm