{"id":18320315,"url":"https://github.com/tpm2-software/tpm2-totp","last_synced_at":"2025-04-09T13:05:57.807Z","repository":{"id":34539856,"uuid":"167222458","full_name":"tpm2-software/tpm2-totp","owner":"tpm2-software","description":"Attest the trustworthiness of a device against a human using time-based one-time passwords","archived":false,"fork":false,"pushed_at":"2024-06-26T20:18:49.000Z","size":243,"stargazers_count":171,"open_issues_count":16,"forks_count":37,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-02T11:02:57.320Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://tpm2-software.github.io","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tpm2-software.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-23T17:15:54.000Z","updated_at":"2025-03-19T04:22:06.000Z","dependencies_parsed_at":"2024-06-19T06:12:00.165Z","dependency_job_id":"ced87e63-d0de-4727-9b15-cc65a8621dd3","html_url":"https://github.com/tpm2-software/tpm2-totp","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpm2-software%2Ftpm2-totp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpm2-software%2Ftpm2-totp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpm2-software%2Ftpm2-totp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpm2-software%2Ftpm2-totp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tpm2-software","download_url":"https://codeload.github.com/tpm2-software/tpm2-totp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045231,"owners_count":21038553,"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-11-05T18:15:53.971Z","updated_at":"2025-04-09T13:05:57.781Z","avatar_url":"https://github.com/tpm2-software.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Linux Build Status](https://github.com/tpm2-software/tpm2-totp/workflows/Linux%20Build%20Status/badge.svg)](https://github.com/tpm2-software/tpm2-totp/actions)\n[![Code Coverage](https://codecov.io/gh/tpm2-software/tpm2-totp/branch/master/graph/badge.svg)](https://codecov.io/gh/tpm2-software/tpm2-totp)\n[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/tpm2-software/tpm2-totp.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/tpm2-software/tpm2-totp/context:cpp)\n[![Coverity Scan](https://scan.coverity.com/projects/22811/badge.svg)](https://scan.coverity.com/projects/tpm2-totp)\n\n# Overview\nThis is a reimplementation of Matthew Garrett's\n[tpmtotp](https://github.com/mjg59/tpmtotp) software for TPM 2.0 using the\n[tpm2-tss](https://github.com/tpm2-software/tpm2-tss) software stack. Its\npurpose is to attest the trustworthiness of a device against a human using\ntime-based one-time passwords (TOTP), facilitating the Trusted Platform Module\n(TPM) to bind the TOTP secret to the known trustworthy system state. In\naddition to the original tpmtotp, given the new capabilities of in-TPM HMAC\ncalculation, the tpm2-totp's secret HMAC keys do not have to be exported from\nthe TPM to the CPU's RAM on boot anymore. Another addition is the ability to\nrebind an old secret to the current PCRs in case a software component was\nchanged on purpose, using a user-defined password.\n\n# Operations\n## Setup\nWhen the platform is in a known trustworthy state, the user will generate a\ntpm2-totp secret that is sealed to the current PCR values of the TPM. The\nsecret is also exported (e.g. via QR-Code) so it can be recorded in a TOTP\napplication (e.g. freeotp on Android phones). The secret is also stored inside\nthe TPM's NV space.\n\n## Boot\nDuring boot the OS sends the current time to the TPM. The TPM checks that the\ncorrect PCR values are present and calculates the HMAC of the time input. This\nresult is the TOTP value that will be displayed to the user. The user can\ncompare this value to the TOTP value of his/her external device (e.g. phone) and\nthus assert the unalteredness and trustworthiness of his/her device.\n\n## Recovery\nIf the TOTP secret on the external device gets lost, there is a way to recover\nthe secret, if a password was set during its generation. In this case the same\nQR code will be displayed to the user again.\n\nIf an update occurs that changes one of the PCR values (e.g. BIOS or Bootloader)\nthen the secret can be resealed to the new PCR values using the password. Then\nit will be available again on the next boot.\n\n# Build and install instructions\nStandard installation using\n```\n./bootstrap\n./configure\nmake\nmake install\n```\nFollowed by setting up the initrd, see below.\n\nInstructions on packages needed to build and install tpm2-totp and different\nbuild options are available in the [INSTALL](INSTALL.md) file.\n\n# Initramfs integration\nThe project includes hooks for [dracut](https://dracut.wiki.kernel.org/),\n[initramfs-tools](https://wiki.debian.org/initramfs-tools) and\n[mkinitcpio](https://wiki.archlinux.org/index.php/Mkinitcpio) to display\nthe TOTP during boot using [Plymouth](https://www.freedesktop.org/wiki/Software/Plymouth/).\nThey are automatically installed if the corresponding tool is found on the\nsystem (also see [INSTALL](INSTALL.md) regarding necessary configuration\noptions). To use them, install tpm2-totp and initialize a TOTP secret, then enable\nthe tpm2-totp hook in your initramfs generator and rebuild the initramfs.\n\n# Usage\n\n## Setup\nThe TOTP secret can be initialized with and without password. It is recommended to\nset a password `-P` in order to enable recovery options. Further, it is strongly\nrecommended to provide the password via stdin, rather than directly as a\ncommand line option, to protect it from other processes, shell history, etc.\nAlso the PCRs and PCR banks can be selected `-p` and `-b`. Default values are\nPCRs `0,2,4` and banks `SHA1, SHA256`.\n```\ntpm2-totp init\n\ntpm2-totp -P - init\nverysecret\u003cCTRL-D\u003e\n# or (recommended)\ngpg --decrypt /path/to/password.gpg | tpm2-totp -P - init\n# or (discouraged)\ntpm2-totp -P verysecret init\n\ntpm2-totp -P - -p 0,1,2,3,4,5,6 init\ntpm2-totp -p 0,1,2,3,4,5,6 -b SHA1,SHA256 init\n```\n\n## Boot\nDuring boot the TOTP value for the current time, together with the current time\nshould be shown to the user, e.g. using plymouth from mkinitrd or from dracut.\nThe command to be executed is:\n```\ntpm2-totp show\ntpm2-totp -t show\n```\n\n## Recovery\nIn order to recover the QR code:\n```\ntpm2-totp -P - recover\n```\nIn order to reseal the secret:\n```\ntpm2-totp -P - reseal\ntpm2-totp -P - -p 1,3,5,6 reseal\n```\n\n## Deletion\nIn order to delete the created NV index:\n```\ntpm2-totp clean\n```\n\n## NV index\nAll command additionally take the `-N` option to specify the NV index to be\nused. By default, 0x018094AF is used and recommended.\n```\ntpm2-totp -N 0x01800001 -P - init\ntpm2-totp -N 0x01800001 show\ntpm2-totp -N 0x01800001 -P - recover\ntpm2-totp -N 0x01800001 -P - reseal\n```\n\n# Limitations\nWhilst tpm2-totp provided the added security (in comparison to tpm-totp) that\nthe key will not leave the TPM during the calculate operation, the time source\nis still not trustworthy and thus an attacker might in some situations be able\nto calculate a set of TOTP values for the future. Depending on the size of the\npossible attack window this can be very large though.\n\nIt is not yet possible to specify specific PCR values independent of the\ncurrently set PCR values. This would allow disabling the password-less calculate\noperation after booting the device. This makes most sense, once a TSS2 FAPI\nis available that will enable an interface to a canonical PCR event log.\n\nCurrently, an empty owner password is assumed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftpm2-software%2Ftpm2-totp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftpm2-software%2Ftpm2-totp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftpm2-software%2Ftpm2-totp/lists"}