{"id":13668742,"url":"https://github.com/bloomberg/spire-tpm-plugin","last_synced_at":"2025-05-07T14:41:54.432Z","repository":{"id":44671742,"uuid":"209627021","full_name":"bloomberg/spire-tpm-plugin","owner":"bloomberg","description":"Provides agent and server plugins for SPIRE to allow TPM 2-based node attestation.","archived":false,"fork":false,"pushed_at":"2023-07-05T20:53:23.000Z","size":152,"stargazers_count":80,"open_issues_count":8,"forks_count":19,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-19T23:31:59.543Z","etag":null,"topics":["spiffe","spire","tpm-attestation","tpm2"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloomberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2019-09-19T18:52:06.000Z","updated_at":"2025-04-17T18:14:37.000Z","dependencies_parsed_at":"2024-01-29T15:10:21.592Z","dependency_job_id":null,"html_url":"https://github.com/bloomberg/spire-tpm-plugin","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fspire-tpm-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fspire-tpm-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fspire-tpm-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fspire-tpm-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/spire-tpm-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252897433,"owners_count":21821436,"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":["spiffe","spire","tpm-attestation","tpm2"],"created_at":"2024-08-02T08:00:48.443Z","updated_at":"2025-05-07T14:41:54.408Z","avatar_url":"https://github.com/bloomberg.png","language":"Go","funding_links":[],"categories":["Utils"],"sub_categories":["SDK"],"readme":"# SPIRE TPM Plugin\n\nThis repository contains agent and server plugins for [SPIRE](https://github.com/spiffe/spire) to allow TPM 2-based node attestation.\n\n## Menu\n\n- [Quick start](#quick-start)\n- [How it Works](#how-it-works)\n- [Building](#building)\n- [Contributions](#contributions)\n- [License](#license)\n- [Code of Conduct](#code-of-conduct)\n- [Security Vulnerability Reporting](#security-vulnerability-reporting)\n\n## Demo\n\nHere's a quick demo that shows how this plugin looks when run:\n\n[![asciicast](https://asciinema.org/a/n0TUMXXlbPUpNtxGxzD0AWzdf.svg)](https://asciinema.org/a/n0TUMXXlbPUpNtxGxzD0AWzdf)\n\n## Quick Start\n\nBefore starting, create a running SPIRE deployment and add the following configuration to the agent and server:\n\n### Agent Configuration\n\n```hcl\nNodeAttestor \"tpm\" {\n\tplugin_cmd = \"/path/to/plugin_cmd\"\n\tplugin_checksum = \"sha256 of the plugin binary\"\n\tplugin_data {\n\t}\n}\n```\n\n### Server Configuration\n\n```hcl\nNodeAttestor \"tpm\" {\n\tplugin_cmd = \"/path/to/plugin_cmd\"\n\tplugin_checksum = \"sha256 of the plugin binary\"\n\tplugin_data {\n\t\tca_path = \"/opt/spire/.data/certs\"\n\t\thash_path = \"/opt/spire/.data/hashes\"\n\t}\n}\n```\n\n| key | type | required | description | default |\n|:----|:-----|:---------|:------------|:--------|\n| ca_path | string |   | the path to the CA directory | /opt/spire/.data/certs |\n| hash_path | string |   | the path to the Hash directory | /opt/spire/.data/hashes |\n\n### Directory Configuration\n\nFor this plugin to work, either `ca_path`, `hash_path`, or both must be configured.\n\n#### Certificate Directory\n\nContains the manufacturer CA cert that signed the TPM's EK certificate in PEM or DER format. Drop all manufacturer CA certs in the directory `ca_path`.\n\n*Note: not all TPM's have an EK certificate, if yours does not then use `hash_path`*\n\n#### Hash Directory\n\nContains empty files named after the EK public key hash.  Use the `get_tpm_pubhash` command to print out the TPM's EK public key hash.  Example:\n\n```bash\nagent  $ ./get_tpm_pubhash\n1b5bbe2e96054f7bc34ebe7ba9a4a9eac5611c6879285ceff6094fa556af485c \n\nserver $ mkdir -p /opt/spire/.data/hashes\nserver $ touch /opt/spire/.data/hashes/1b5bbe2e96054f7bc34ebe7ba9a4a9eac5611c6879285ceff6094fa556af485c\n```\n\n## How it Works\n\nThe plugin uses TPM credential activation as the method of attestation. The plugin operates as follows:\n\n1. Agent generates AK (attestation key) using TPM\n1. Agent sends the AK attestation parameters and EK certificate or public key to the server\n1. Server inspects EK certificate or public key\n    1. If `hash_path` exists, and the public key hash matches filename in `hash_path`, validation passes\n    1. If `ca_path` exists, and the EK certificate was signed by any chain in `ca_path`, validation passes\n1. If validation passed, the server generates a credential activation challenge using\n    1. The EK public key\n    1. The AK attestation parameters\n1. Server sends challenge to agent\n1. Agent decrypts the challenge's secret \n1. Agent sends back decrypted secret\n1. Server verifies that the decrypted secret is the same it used to build the challenge\n1. Server creates a SPIFFE ID in the form of `spiffe://\u003ctrust_domain\u003e/agent/tpm/\u003csha256sum_of_tpm_pubkey\u003e`\n1. All done!\n\nFor info on how TPM attestation usually works and how this implementation differs, visit [TPM.md](TPM.md).\n\n## Building\n\nTo build this plugin on Linux, run `make build`. Because of the dependency on [go-attestation](https://github.com/google/go-attestation), you must have `libtspi-dev` installed.\n\n## Contributions\n\nWe :heart: contributions.\n\nHave you had a good experience with this project? Why not share some love and contribute code, or just let us know about any issues you had with it?\n\nWe welcome issue reports [here](../../issues); be sure to choose the proper issue template for your issue, so that we can be sure you're providing the necessary information.\n\nBefore sending a [Pull Request](../../pulls), please make sure you read our\n[Contribution Guidelines](https://github.com/bloomberg/.github/blob/master/CONTRIBUTING.md).\n\n## License\n\nPlease read the [LICENSE](LICENSE) file.\n\n## Code of Conduct\n\nThis project has adopted a [Code of Conduct](https://github.com/bloomberg/.github/blob/master/CODE_OF_CONDUCT.md).\nIf you have any concerns about the Code, or behavior which you have experienced in the project, please\ncontact us at opensource@bloomberg.net.\n\n## Security Vulnerability Reporting\n\nIf you believe you have identified a security vulnerability in this project, please send email to the project\nteam at opensource@bloomberg.net, detailing the suspected issue and any methods you've found to reproduce it.\n\nPlease do NOT open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports private until\nwe've had an opportunity to review and address them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fspire-tpm-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Fspire-tpm-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fspire-tpm-plugin/lists"}