A TPM backend for Sequoia's private key store. The `sequoia-keystore` crate implements a server that manages secret keys. Secret key material can be stored in files, on hardware devices like smartcards, or accessed via the network. `sequoia-keystore` doesn't implement these access methods. This is taken care of by various backends. This crate includes a backend that exposes the secret keys managed by a TPM. # Using your TPM In TPM terminology, keys are named by handles. To list any persistent keys, use `tpm2_getcap` (from the `tpm2-tools` package in Debian) do the follow as root or add yourself to the appropriate group (`tss` on Debian, or examine `/dev/tpmrm0`): ```text $ tpm2_getcap handles-persistent - 0x81000001 - 0x81000002 - 0x81010001 ``` To create a key on the TPM, you can use `create-key` from [`sequoia-tpm`], as well the templates [`rsa2k-dec.yml`] and [`rsa2k-sign.yml`] from this project. [`sequoia-tpm`]: https://gitlab.com/sequoia-pgp/sequoia-tpm [`rsa2k-dec.yml`]: https://gitlab.com/sequoia-pgp/sequoia-keystore/-/blob/main/tpm/examples/rsa2k-dec.yml [`rsa2k-sign.yml`]: https://gitlab.com/sequoia-pgp/sequoia-keystore/-/blob/main/tpm/examples/rsa2k-sign.yml ```text $ /tmp/sequoia-tpm/target/debug/create-key --file .../sequoia-keystore/tpm/examples/rsa2k-dec.yml Generated key handle = 0x40418488 $ /tmp/sequoia-tpm/target/debug/create-key --file .../sequoia-keystore/tpm/examples/rsa2k-sign.yml Generated key handle = 0x40418488 ``` The handles that are shown are the temporary handles. The persistent handles are set in the `yaml` files. In my case, we can see that two persistent handles have been added: ```text $ tpm2_getcap handles-persistent - 0x81000001 - 0x81000002 - 0x81000018 - 0x81000027 - 0x81010001 ``` To delete a key do: ``` $ tpm2_evictcontrol --object-context=0x81000027 persistent-handle: 0x81000027 action: evicted ``` To get the public key, we use `get-key` from `sequoia-tpm`. For example: ```text $ /tmp/sequoia-tpm/target/debug/get-key --file .../sequoia-keystore/tpm/examples/rsa2k-sign.yml --- spec: provider: tpm: tcti: "device:/dev/tpmrm0" handle: 2164260903 parent: ~ private: ~ unique: RSA: bytes: d800779885492a9e3712880bbaefe348365eff39bb0fabf92262e01b3d96efc723ab69eee2e32a0ca4687e0562182ff4343cbd3ade5091bcb4e220c02cc741c39765e5a38490c69dda7bfad8ae0b1b521ec47f37fafb3b0570618155441ed516d6b1e0c09a97065800a54d9837fc4a9ef3b9d568b4ef69ce4db36097c31b35775e743c43fef19591f0cf444511f561eb2cecc3c5f3c18912ea060500026c338548682ce894313e54846e0e4b3e421250c9a844e67ce470e909f4b7a1f065b83c391164528fd12e0a4581340500e2c6863342304b5eb56df09e7083c0a826853c3ecf436294e2c06ad7090e74ba6f78e7450c6002d80ee15e7ea1f364bc39f071 wrapped: ~ policy: "" algo: RSA: bits: 2048 exponent: ~ private: ~ capabilities: - sign auth: "123" ``` To add the key to the keystore, copy the descriptions to the home directory for the keystore's tpm: ```text $ mkdir -p ~/.local/share/sequoia/keystore/tpm $ cp .../sequoia-keystore/tpm/examples/rsa2k-{dec,sign}.yml ~/.local/share/sequoia/keystore/tpm ``` `sq` is not yet able to use the keys. For that we have to add OpenPGP metadata to the keys, and then add the keys to an OpenPGP certificate. For the first part, we create a "null" OpenPGP certificate using the `get-openpgp-key` utility from `sequoia-tpm`. A null OpenPGP certificate is just a certificate with a single packet: a primary key, whose creation time is set to the unix epoch. It doesn't have any signatures, so it is not a valid certificate, but `sq` can work with it. ```text $ /tmp/sequoia-tpm/target/debug/get-openpgp-key --file ~/.local/share/sequoia/keystore/tpm/rsa2k-sign.yml >/tmp/sign.pgp $ sq inspect /tmp/sign.pgp /tmp/sign.pgp: Revocation Certificate. Fingerprint: E5637B7762959BB59ACB8E9426F9CAC1FA7C375F Invalid: No binding signature at time 2024-08-29T09:29:30Z Public-key algo: RSA Public-key size: 2048 bits Creation time: 1970-01-01 00:00:00 UTC $ /tmp/sequoia-tpm/debug/get-openpgp-key --file ~/.local/share/sequoia/keystore/tpm/rsa2k-dec.yml >/tmp/dec.pgp $ sq inspect /tmp/dec.pgp /tmp/dec.pgp: Revocation Certificate. Fingerprint: B321BA8F650CB16443E06826DBFA98A78CF6562F Invalid: No binding signature at time 2024-08-29T09:29:39Z Public-key algo: RSA Public-key size: 2048 bits Creation time: 1970-01-01 00:00:00 UTC ``` We import the null certificates into `sq`, and the keys now appear: ```text $ sq cert import /tmp/sign.pgp /tmp/dec.pgp Imported E5637B7762959BB59ACB8E9426F9CAC1FA7C375F, Imported B321BA8F650CB16443E06826DBFA98A78CF6562F, Imported 2 new certificates, updated 0 certificates, 0 certificates unchanged, 0 errors. $ sq key list - softkeys - tpm - device:/dev/tpmrm0 - B321BA8F650CB16443E06826DBFA98A78CF6562F (available, unlocked, for decryption) - E5637B7762959BB59ACB8E9426F9CAC1FA7C375F (available, unlocked, for signing) ... ``` For the keys to be useful, we need to add them to a certificate. In the following example, we create a new certification-only certificate. We don't add any subkeys, since we want to use the decryption and signing keys on the TPM. You could use an existing certificate. ```text $ sq key generate --email test@example.org --cannot-encrypt --cannot-sign --cannot-authenticate Please enter the password to protect key (press enter to not use a password): Please repeat the password: Transferable Secret Key. Fingerprint: 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B Public-key algo: EdDSA Public-key size: 256 bits Secret key: Unencrypted Creation time: 2024-08-29 09:16:26 UTC Expiration time: 2027-08-30 02:42:47 UTC (creation time + 2years 11months 30days 9h 16m 45s) Key flags: certification UserID: $ sq pki link add --ca \* 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B --all Linking 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B and "". $ sq key adopt --can-encrypt=universal --expiration 2030-01-01 --cert 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B --key B321BA8F650CB16443E06826DBFA98A78CF6562F Hint: Imported updated cert into the cert store. To make the update effective, it has to be published so that others can find it, for example using: sq network keyserver publish --cert FE61C03A3EB58C7B $ sq key adopt --cert 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B --key E5637B7762959BB59ACB8E9426F9CAC1FA7C375F --can-sign --expiration 2030-01-01 Hint: Imported updated cert into the cert store. To make the update effective, it has to be published so that others can find it, for example using: sq network keyserver publish --cert FE61C03A3EB58C7B $ sq inspect --cert 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7BOpenPGP Certificate. Fingerprint: 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B Public-key algo: EdDSA Public-key size: 256 bits Creation time: 2024-08-29 09:16:26 UTC Expiration time: 2027-08-30 02:42:47 UTC (creation time + 2years 11months 30days 9h 16m 45s) Key flags: certification Subkey: B321BA8F650CB16443E06826DBFA98A78CF6562F Public-key algo: RSA Public-key size: 2048 bits Creation time: 1970-01-01 00:00:00 UTC Expiration time: 2030-01-01 00:00:00 UTC (creation time + 60years) Key flags: transport encryption, data-at-rest encryption Subkey: E5637B7762959BB59ACB8E9426F9CAC1FA7C375F Public-key algo: RSA Public-key size: 2048 bits Creation time: 1970-01-01 00:00:00 UTC Expiration time: 2030-01-01 00:00:00 UTC (creation time + 60years) Key flags: signing, transport encryption, data-at-rest encryption UserID: ``` Finally, we can create signatures and decrypt messages using our OpenPGP certificate: ```text $ echo a message | sq sign --signer-key 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B | sq verify Authenticating 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B ("") using the web of trust: Fully authenticated (120 of 120) 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B, ◯ DBDE6D01BBE73919A2645E60CB2308D04C8D0A6A ("Local Trust Root") │ certified the following binding on 2024-08-29 as a fully trusted meta-introducer (depth: │ unconstrained) └ 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B "" Good signature from 26F9CAC1FA7C375F ("") a message 1 good signature. $ echo a message | sq encrypt --recipient-cert 5D4FE5AC4549548192AD2AFBFE61C03A3EB58C7B | sq decrypt Encrypted using AES-256 a message ```