{"id":22700215,"url":"https://github.com/simp/pupmod-simp-tpm","last_synced_at":"2025-04-13T05:53:46.490Z","repository":{"id":32298737,"uuid":"35873698","full_name":"simp/pupmod-simp-tpm","owner":"simp","description":"The SIMP tpm Puppet Module","archived":false,"fork":false,"pushed_at":"2024-08-20T19:54:11.000Z","size":417,"stargazers_count":7,"open_issues_count":2,"forks_count":15,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-13T05:53:39.518Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-19T09:49:43.000Z","updated_at":"2024-07-11T21:09:28.000Z","dependencies_parsed_at":"2022-07-12T10:31:02.410Z","dependency_job_id":"fecdd720-5299-4f95-ba20-38666f4b48b1","html_url":"https://github.com/simp/pupmod-simp-tpm","commit_stats":{"total_commits":81,"total_committers":12,"mean_commits":6.75,"dds":0.617283950617284,"last_synced_commit":"45a15a4ca7c9394992aacae484787a731c3c6ffe"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-tpm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-tpm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-tpm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simp%2Fpupmod-simp-tpm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simp","download_url":"https://codeload.github.com/simp/pupmod-simp-tpm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670502,"owners_count":21142901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-10T06:10:31.869Z","updated_at":"2025-04-13T05:53:46.469Z","avatar_url":"https://github.com/simp.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License](http://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/73/badge)](https://bestpractices.coreinfrastructure.org/projects/73)\n[![Puppet Forge](https://img.shields.io/puppetforge/v/simp/tpm.svg)](https://forge.puppetlabs.com/simp/tpm)\n[![Puppet Forge Downloads](https://img.shields.io/puppetforge/dt/simp/tpm.svg)](https://forge.puppetlabs.com/simp/tpm)\n[![Build Status](https://travis-ci.org/simp/pupmod-simp-tpm.svg)](https://travis-ci.org/simp/pupmod-simp-tpm)\n\n#### Table of Contents\n\n1. [Description](#description)\n2. [Setup - The basics of getting started with tpm](#setup)\n    * [What tpm affects](#what-tpm-affects)\n    * [Setup requirements](#setup-requirements)\n    * [Beginning with the tpm](#beginning-with-the-tpm-module)\n3. [Usage - Configuration options and additional functionality](#usage)\n4. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [Development - Guide for contributing to the module](#development)\n    * [Acceptance Tests - Beaker env variables](#acceptance-tests)\n\n\n## Description\n\nThis module manages TPM, including taking ownership. You must take ownership of\na TPM to load and unload certs, use it as a PKCS #11 interface, or to use\nSecureBoot.\n\nThe TPM ecosystem has been designed to be difficult to automate. The difficulty\nhas shown many downsides of using a tool like this module to manage your\nTPM device. For example, simply reading the TPM's public key after taking\nownership of the device requires the owner password to be typed in at the\ncommand line. This is an intentional feature to encourage admins to be\nphysically present at the machine with the device. To get around this, the\nprovider included in this module and the advanced facts use Ruby's `expect`\nlibrary to interact with the command line. This module also drops the owner\npassword in the Puppet `$vardir` to make interacting with trousers in facts\npossible.\n\n\n### This is a SIMP module\n\nThis module is a component of the [System Integrity Management Platform](https://simp-project.com),\na compliance-management framework built on Puppet.\n\nIf you find any issues, they may be submitted to our [bug tracker](https://simp-project.atlassian.net/).\n\nThis module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:\n\n * When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.\n * 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.\n\n\n## Setup\n\n\n### What tpm affects\n\n--------------------------------------------------------------------------------\n\u003e **WARNING**\n\u003e\n\u003e This module can take ownership of your TPM. This could be a destructive\n\u003e process and is not easily reversed. For that reason, the provider does not\n\u003e support clearing a TPM.\n\n--------------------------------------------------------------------------------\n\nThis module will:\n* Install `tpm-tools` and `trousers`\n* Enable the `tcsd` service\n* (*OPTIONAL*) Take ownership of the TPM\n  * The password will be in a flat file in `$vardir/simp`\n* (*OPTIONAL*) Install `tboot`, create policy, and add grub entry\n\n\n### Setup Requirements\n\nIn order to use this module or a TPM in general, you must do the following:\n\n1. Enable the TPM in BIOS\n2. Set a user/admin BIOS password\n3. Be able to type in the user/admin password at boot time, every boot\n\n\n### Beginning with the TPM module\n\n--------------------------------------------------------------------------------\n\u003e **NOTE**\n\u003e\n\u003e Using the 'well-known' SRK password is not recommended for actual use,\n\u003e but it is required for both Intel TXT (Trusted Boot) and the [PKCS#11\n\u003e interface](http://trousers.sourceforge.net/pkcs11.html). If you aren't using\n\u003e either of those technologies, please use a real password.\n\n--------------------------------------------------------------------------------\n\nInclude the TPM class and set the passwords in hiera. If either of the passwords\nare the string 'well-known', then the well known option will be added to the\n`tpm_takeownership` command used to take ownership of the TPM:\n\n```yaml\nclasses:\n  - tpm\n\ntpm::take_ownership: true\ntpm::ownership::advanced_facts: true\n\ntpm::ownership::owner_pass: 'twentycharacters0000'\ntpm::ownership::srk_pass: 'well-known'\n```\n\nTo enable the PKCS#11 interface, add the `tpm::pkcs11` class to your node and set the PINs in hiera:\n\n```yaml\nclasses:\n  - tpm::pkcs11\n\ntpm::pkcs11::so_pin: '12345678'\ntpm::pkcs11::user_pin: '87654321'\n```\n\nTo start with Trusted Boot follow the directions below carefully.\n\n## Usage\n\n### Ownership\n\nThe type and provider for tpm ownership provided in this module can be used as follows:\n\n```puppet\ntpm_ownership { 'tpm0':\n  ensure         =\u003e present,\n  owner_pass     =\u003e 'well-known',\n  srk_pass       =\u003e 'well-known',\n  advanced_facts =\u003e true\n}\n```\n\n### PKCS#11\n\nThe PKCS#11 slot type and provider can be enabled as follows:\n\n```puppet\ntpmtoken { 'TPM PKCS#11 token':\n  ensure   =\u003e present,\n  so_pin   =\u003e '12345678',\n  user_pin =\u003e '87654321'\n}\n```\n\n### Trusted Boot\n\nThis module supports versions of tboot 1.9.6 and later.\nThis module only supports grub2.\n\n#### Known Errors\nThere are known errors in tboot v1.9.6 and the creation of the LCP and VLP\nfail with memory errors.  This was fixed in  tboot v1.9.7.\n\nBy default policy creation is disabled because as of Sept 06, 2018 tboot\nv1.9.6 is the version delivered with RedHat 7.5.\nIf you want to compile tboot yourself the source can be obtained from the sourceforge:\n https://sourceforge.net/projects/tboot/\n\nIn order to check if tboot version is \u003e 1.9.6 and policy is not true\nit needs to do two passes because the fact for the version is executed\nbefore the module installs tboot.\n\nTo avoid this the tboot version can be set in hiera:\n\n```yaml\n---\ntpm::tboot::tboot_version: \"1.9.6\"\n```\n\n#### Setting up trusted boot\n\nTo set up trusted boot on a system do the following:\n\n1. Make sure the TPM owner password is 20 characters long and the SRK password\n   is 'well-known', equivalent to `tpm_takeownership -z`\n2. Download the appropriate SINIT for your platform from the [Intel website](https://software.intel.com/en-us/articles/intel-trusted-execution-technology)\n3. Extract the zip and put it on a webserver somewhere or in a profile module.\n4. Set the following data in hiera:\n\n```yaml\n---\ntpm::tboot::sinit_name: 2nd_gen_i5_i7_SINIT_51.BIN # the appropriate BIN\ntpm::tboot::sinit_source: 'puppet:///profiles/2nd_gen_i5_i7_SINIT_51.BIN' # where ever you choose to stash this\ntpm::tboot::owner_password: \"%{alias('tpm::ownership::owner_pass')}\"\ntpm::ownership::owner_pass: \"whatever your password is\"\n# If you are using version 1.9.7 or later and want the LCP and VLP updated:\ntpm::tboot::create_policy: true\n# To avoid puppet having to do 2 passes to determine what version of tboot is installed\n# you can set the version of tboot.\ntpm::tboot::tboot_version: \"1.9.6\"\n```\n\n5. Include the `tpm::tboot` class:\n\n```yaml\n---\nclasses:\n  - tpm\n  - tpm::tboot\n```\n\n6. Run puppet (run it twice if you have not set the tboot version).\n   Reboot and select the tboot option from the menu.\n7. Check the `tboot` fact for a measured launch: `puppet facts | grep measured_launch` or just run `txt-stat`\n\n#### Removing other options from the boot menu\n\nIf only the tboot menu option should be available to users then set the following in hiera:\n\n```yaml\n---\ntpm::tboot::purge_boot_entries: true\n```\n\nThis removes the execute permissions from the /etc/grub.d/10_linux file.\nIf you decide to remove tboot later, these permissions will need to\nbe set back to executable and the grub2-mkconfig run again.\n\n#### Locking the kernel\n\nThe `tpm::tboot` class will use the `yum::versionlock` define from the\n`voxpupuli/yum` module to make sure the version of the kernel that the tboot\npolicy was created with doesn't get upgraded without the user knowing. To\ndisable this, set the `tpm::tboot::lock_kernel_packages` parameter to `false`.\n\nThis module does provide a script to upgrade the policy, though it shouldn't be\nrun from Puppet. To update your verified launch policy, do the following steps:\n\n1. `yum update kernel`\n2. `grub2-mkconfig -o /etc/grub2.cfg`\n3. `sh /root/txt/txt/update_tboot_policy.sh \u003cowner password\u003e`\n\nAnd reboot!\n\n## Reference\n\nSee [REFERENCE.md](REFERENCE.md) for API details.\n\n## Limitations\n\nSIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux\nand compatible distributions, such as CentOS. Please see the\n[`metadata.json` file](./metadata.json) for the most up-to-date list of\nsupported operating systems, Puppet versions, and module dependencies.\n\nThis module does not support clearing a previously owned TPM.\n\n## Development\n\nPlease read our [Contribution Guide](https://simp.readthedocs.io/en/stable/contributors_guide/Contribution_Procedure.html)\n\n\n### Acceptance tests\n\n**TODO:** There are currently no acceptance tests. We would need to use a\n[virtual TPM](https://github.com/stefanberger/swtpm/) to ensure test system\nstability, and it requires quite a few patches to libvirt, associated\nemulation software, Beaker, and Vagrant before acceptance tests for this module become feasible. Read\nour [progress so far on the issue](https://simp-project.atlassian.net/wiki/x/CgAVAg).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimp%2Fpupmod-simp-tpm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimp%2Fpupmod-simp-tpm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimp%2Fpupmod-simp-tpm/lists"}