{"id":19665277,"url":"https://github.com/alttch/tpm-km","last_synced_at":"2025-04-28T22:31:05.755Z","repository":{"id":103749303,"uuid":"207860329","full_name":"alttch/tpm-km","owner":"alttch","description":"yet another pack of scripts for TPM2+Luks","archived":false,"fork":false,"pushed_at":"2021-12-23T19:40:25.000Z","size":33,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-05T11:24:26.323Z","etag":null,"topics":["encryption","encryption-management","linux","luks","secure-boot","tpm2"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alttch.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-11T16:42:35.000Z","updated_at":"2023-08-20T17:01:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"c5637baf-ce08-4adc-abce-1c9bfb78002a","html_url":"https://github.com/alttch/tpm-km","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Ftpm-km","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Ftpm-km/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Ftpm-km/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Ftpm-km/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alttch","download_url":"https://codeload.github.com/alttch/tpm-km/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251397577,"owners_count":21583034,"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":["encryption","encryption-management","linux","luks","secure-boot","tpm2"],"created_at":"2024-11-11T16:21:54.731Z","updated_at":"2025-04-28T22:31:05.720Z","avatar_url":"https://github.com/alttch.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tpm-km\n\nYet another pack of scripts for TPM2+luks and similar tasks.\n\n## Why\n\ntpm-km can:\n\n* verify PCR state before sealing key and abort if any PCRs are empty\n* protect the key with additional PIN (AES256)\n* ask for PINs and passwords in pretty dialog windows\n* split the secret key in chunks and protect them with different PCR policies\n\n![pin dialog](https://github.com/alttch/tpm-km/blob/master/images/dialog.png?raw=true)\n\n## Setup\n\n* Install *dialog*, *tpm2-tools* (make sure you have 3.x or above) and *figlet*\n  (optional)\n\n```shell\n    sudo apt -y install dialog tpm2-tools figlet\n```\n\n* Clear TPM2 module and take ownership\n\n```shell\n    sudo tpm2_clear\n    # for tpm2 tools below v4:\n    # sudo tpm2_takeownership -c\n```\n\n* If you have graphics splash screen - remove it, otherwise you won't see\n  PIN/password dialog windows: make sure there's no *splash* in\n  */etc/default/grub*. If exists - remove it and run *update_grub* to apply the\n  new configuration.\n\n* Install tpm-km\n\n```shell\n    sudo ./install.sh\n```\n\nInstall script copies:\n\n* /usr/local/sbin/generate-secret-key.sh - key generator\n* /usr/local/sbin/seal-tpm.sh - TPM sealing script\n* /sbin/getsecret.sh - TPM reader script\n* /etc/initramfs-tools/hooks/tpm-hook - initramfs-ready TPM hook\n* /usr/local/etc/tpm_km - configuration file\n\n* It's also strongly recommended to configure UEFI Secure Boot and use grub \u003e=\n  2.04 (or systemd-boot), as grub prior 2.04 doesn't fill all TPM registers and\n  your system can be owned if someone compromise the kernel or initrd.\n\n## Generate key and seal it to TPM\n\n* Generate the secret key. By default, 128-bytes alpha-numeric key is generated\n  (as tpm-km is written in bash and doesn't like binary data) and put in\n  /secret.key file with 000 permissions.\n\n```shell\n    sudo /usr/local/sbin/generate-secret-key.sh\n```\n\n* Add the key to luks:\n\n```shell\n    sudo cryptsetup luksAddKey /dev/my-encrypted-drive /secret.key\n```\n\n* Put TPM reader script into /etc/crypttab:\n\n```\n    \u003ccontainer\u003e  UUID=\u003cFS_UUID\u003e   none    luks,discard,initramfs,keyscript=/sbin/getsecret.sh\n```\n\n* Re-create initial ramdisk:\n\n```shell\n    sudo update-initramfs -u -v\n```\n\nIt's also recommended to backup previous initrd\\*.img files to rollback them if\nanything go wrong.\n\n* **Reboot** the system with the new ramdisk. TPM reader script will report an\n  error, that's fine. Enter your usual luks password, when prompted.\n\n* Seal the key to TPM:\n\n```shell\n    sudo /usr/local/sbin/seal-tpm.sh\n```\n\nYou'll be prompted for PIN, twice.\n\n* Reboot again and enter your PIN instead of the password. If it works -\n  congrats, you have TPM2+luks with PIN protection.\n\nThe key must be re-sealed into TPM every time when something in the system is\nchanged (depending which PCRs are used).\n\nIf you want to store sealing PIN, put it to file */usr/local/etc/tpm_sealpin*\n(don't forget to set 600 permissions on it).\n\n## FAQ\n\n### What is purpose of PIN?\n\nPIN is used to add an additional protection for the system. Without PIN an\nattacker can not boot the system to the login prompt, so he can not use any\nlocal or network exploits.\n\nWhen booted, there are 3 attempts to enter PIN, after the 3rd attempt, the key\nis deleted from TPM.\n\nWARNING: using PIN before v1.2 may be insecure.\n\n### Can I boot my system without PIN?\n\nIf you forgot your PIN, just press Cancel at PIN prompt dialog. The key will be\ndeleted from TPM and the script will fall back to password prompt. After\nbooting, you may re-seal the keys back to TPM.\n\n### Can I disable PIN protection?\n\nThis is insecure, but yes, of course you can. Put a default PIN into the\nconfiguration file and that's it. Don't forget to re-create initrd as well.\n\n### Should PIN be only numeric?\n\nIn tpm-km, PIN is just called \"PIN\", because most of encrypted disk mangers use\nnumeric PINs. Nope - it can be alpha-numeric and include special symbols. It's\nup to you.\n\n### What can be configured?\n\nPIN, key file location, PCR sets, TPM addresses, dialog args (e.g. remove\n--insecure to enter PINs and passwords without asterisks)\n\nEverything else can be configured inside the scripts code. Haha.\n\nNote: after any change in /usr/local/etc/tpm_km you must rebuild initial\nramdisk.\n\n### Does it work with TPM1.2?\n\nNo\n\n### Where can I get grub \u003e= 2.04?\n\nGrub 2.04 is already included in RHEL 8.0, Fedora 30, Ubuntu 19.10 and maybe\nsome other Linux distros.\n\n### What if I don't use grub?\n\nIf you don't use grub (e.g. use systemd-boot instead), remove PCRs 8 and 9 from\n/usr/local/etc/tpm_km (unless they're filled by your loader).\n\n### Why the secret key is being split?\n\nBy default, tpm-km splits key in 2 chunks. TPM 2.0 specification doesn't\nallow TPM policy with more than 8 PCRs at once. With 2 chunks tpm-km can use\nalmost all filled PCRs and make system protection much stronger. Just make sure\nPCRs 0,2,4,7 (and 9 for grub) are present in both sets.\n\n### Compatibility\n\nFor tpm2_tools below 4.0 (e.g. Ubuntu 19.10 and earlier), use release 1.0. For\ntpm2 tools v4 use version 1.1+ or master branch.\n\n### No tpm device during boot\n\nIf initramfs fails with \"/dev/tpm0 not found\" error, make sure TPM modules are\nincluded into the initial ram disk. Add the following to\n/etc/initramfs-tools/modules:\n\n```\ntpm\ntpm_crb\ntpm_tis\ntpm_tis_core\nrng_core\nccp\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falttch%2Ftpm-km","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falttch%2Ftpm-km","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falttch%2Ftpm-km/lists"}