Docker environment for pass password manager, backed by gnupg-pkcs11-scd and tpm2_pkcs11 backend to store gpg keys into TPM.
WARNING: This is a relatively complex setup with lots of links in the chain, Complexity is the enemy of security. I cannot guarantee the absence of bugs or configuration mistakes that would void the security of the whole approach. Therefore, use at your own risk.
Auth model
A summary of the auth model, extracted from tpm2-pkcs11 repo: all tpm2_pkcs11
objects are stored under a peristent primary key in the owner hierarchy. tpm2_pkcs11
library borrows several concepts that are smartcard specific. A slot
is the physical smart card reader slot. For each slot, there could be one or more smartcards, each of which is associated with a token. A token maintains 2 objects under the primary key: one for the SO
user, and the other for the USER
user. The auth value for these objects is the SO
or USER
pin. The auth value is used to unseal an aes256 wrapping key, which in turn is used to encrypt all auth values for the objects in the token (keys and certificates that the token exposes for cryptographic operations). In this setup, the token is associated to a pre-existing transient TPM key stored outside of the TPM (in turn wrapped into a primary key in the owner hierarchy). This to allow for easy migration of this key to a different TPM (with associated policy) to give access to the same gpg-backed keychain on a different machine.
The migration policy used in this setup is a signed policy, which means that migration needs to be allowed by another authority via signature. We use a TPM key generated on the same TPM that hosts the gpg key. Ideally the migration authority should be further protected and stored on a different device.
The instructions below explain how to setup tpm2_pkcs11
store, generate the gpg key and migrate the TPM key to a different machine.
All persitent artifacts (e.g. keys, pass store, etc) are stored on gpg_keys_volume
volume, which is bind mounted on /home/gpg/keys
.
If this volume gets lost (and there is no backup) access to all secrets is lost as well. Obviously, all TPM generated keys are bound
to that single TPM, so losing access to TPM, means also losing access to the keys.
Store initialization
The pkcs11 store needs to be initialized with a token. We'll initialize the store so the token will be associated to a transient external TPM object.
/home/gpg/tpm2-pkcs11/tools/tpm2_ptool.py init --transient-parent tpm2-tools-default --path /home/gpg/keys | grep id | cut -d' ' -f 2-2
Create a token for the store we just initialized: (assuming PID 1):
/home/gpg/tpm2-pkcs11/tools/tpm2_ptool.py addtoken --path /home/gpg/keys --pid=1 --sopin=<SO_PIN> --userpin=<USER_PIN> --label=t_gpg
Create a transient key linked to the token. We create first a primary key in the owner hierachy that will wrap our key.
tpm2_createprimary -c primary.ctx
The key needs to be created as migratable and a policy which protects its migration needs to be assocaited to the key. We want to use a signed policy, so we generate first the signing key which will authorize the migration.
tpm2_create -C primary.ctx -u migration_authority.pub -r migration_authority.priv -p <PASSPHRASE_MIGRATION_AUTHORITY>
Generate the policy which will allow the migration:
tpm2_load -C primary.ctx -u migration_authority.pub -r migration_authority.priv -c migration_authority.ctx
tpm2_startauthsession -S session.ctx
tpm2_policysigned -S session.ctx -g sha256 -c /home/gpg/keys/migration_authority.ctx --raw-data to_sign.bin
tpm2_sign -c migration_authority.ctx -g sha256 -o migration_authority.sig to_sign.bin -p <PASSPHRASE_MIGRATION_AUTHORITY>
tpm2_policysigned -S session.ctx -g sha256 -s migration_authority.sig -c migration_authority.ctx -L migration_policy.policy
tpm2_policycommandcode -S session.ctx -L migration_policy.policy TPM2_CC_Duplicate
tpm2_flushcontext session.ctx
Create a migratable key associated to that policy:
tpm2_create -C primary.ctx -u gpg.pub -r gpg.priv -a "sensitivedataorigin|userwithauth|decrypt|sign" -L migration_policy.signed -p <ENCRYPTION_KEY_PASSPHRASE>
If we wanted to generate the key as persistent object inside the TPM, via tpm2_ptool.py
itself, we would need to use the following command:
/home/gpg/tpm2-pkcs11/tools/tpm2_ptool.py addkey \
--algorithm=rsa2048 \
--label=t_gpg \
--key-label=gpg_key_1 \
--userpin ${USER_PIN} \
--path /home/gpg/.tpm2_pkcs11/
This is not necessary in this case as we are generating the key ourselves.
Link the key we just created with the token:
/home/gpg/tpm2-pkcs11/tools/tpm2_ptool.py link --label=t_gpg --path /home/gpg/keys --userpin <USER_PIN> --key-label="k_gpg" gpg.pub gpg.priv --auth <ENCRYPTION_KEY_PASSPHRASE>
Now generate a certificate for the key, Inspect tokens and call generate_certificate
is the corresponding URL.
p11tool --list-tokens
../scripts/generate_certificate <TOKEN_URL>
Associate the certificate to the token:
/home/gpg/tpm2-pkcs11/tools/tpm2_ptool.py addcert --path /home/gpg/keys --label t_gpg --key-label="k_gpg" cert.pem
Now generate the gpg key
gpgconf --kill all
gpg --card-status
gpg --expert --full-generate-key
We could either use (13) Existing key
or (14) Existing key from card
. With (13)
, we would fist need to acquire they keygrip as follows:
# gpg-agent --server gpg-connect-agent
[...]
> SCD LEARN
[...]
The KEY-FRIEDNLY
entry would give us the keygrip.
Later on it will be useful to list gpg keys with their full IDs:
gpg --keyid-format LONG --list-keys
Migrate key
The procedure below explains how to migrate the gpg key generated above. We'll assume that TPM A
is the origin TPM and TPM B
is the destination TPM.
Create parent object on TPM B
that will be used to wrap/transfer the key. Load it an get the public portion.
tpm2_createprimary -C o -g sha256 -G rsa -c primary.ctx
tpm2_readpublic -c primary.ctx -o new_parent.pub
Transfer new_parent.pub to the machine with TPM A
and load the public part of the new parent key:
tpm2_loadexternal -C o -u new_parent.pub -c new_parent.ctx
Start a policy session to authorize the duplication on machine with TPM A
tpm2_startauthsession -S session.ctx --policy-session
tpm2_policysigned -S session.ctx -g sha256 -c /home/gpg/keys/migration_authority.ctx --raw-data to_sign.bin
tpm2_sign -c /home/gpg/keys/migration_authority.ctx -g sha256 -o sig.rssa to_sign.bin -p
tpm2_policysigned -S session.ctx -g sha256 -c /home/gpg/keys/migration_authority.ctx -s sig.rssa
tpm2_policycommandcode -S session.ctx -L migration_policy.policy TPM2_CC_Duplicate
Now key can be duplicated:
tpm2_duplicate -C new_parent.ctx -c gpg_key.ctx -G null -r dup.dpriv -s dup.seed -p "session:session.ctx"
On TPM A
, also read the public portion of the gpg key and move it to TPM B
:
tpm2_readpublic -c gpg_key.ctx -o gpg_dup.pub
Copy over dup.dpriv
and dup.seed
to TPM B
:
tpm2_import -C primary.ctx -u gpg_dup.pub -i dup.dpriv -r gpg_key.priv -s dup.seed
tpm2_load -C primary.ctx -u gpg_dup.pub -r gpg_key.priv -c gpg_key.ctx
On TPM B
, run the usual import and link steps:
/home/gpg/tpm2-pkcs11/tools/tpm2_ptool.py addtoken --path /home/gpg/keys --pid=1 --sopin=<SO_PIN> --userpin=<USER_PIN> --label=t_gpg
/home/gpg/tpm2-pkcs11/tools/tpm2_ptool.py link --label=t_gpg --path /home/gpg/keys --userpin <USER_PIN> --key-label="k_gpg" gpg_ gpg.priv --auth
../scripts/generate_certificate <TOKEN_URL>
/home/gpg/tpm2-pkcs11/tools/tpm2_ptool.py addcert --path /home/gpg/keys --label t_gpg --key-label="k_gpg" cert.pem
Now, import gpg key from the primary TPM:
gpg --output key.gpg --export <GPG_KEY_EMAIL>
gpg --import key.gpg
Now the gpg key should be usable also on TPM B
.
Bugs
When decrypting a gpg message with the TPM backed key. gpg fails to extract the DEK from the corresponding frame, complaining that cipher algorithm is unknown in get_it
in pubkey-enc.c
. This happens because gpg-agent returns that random bytes padding at the begining of the frame has been removed (i.e. padding = 0
), while this is not the case and DEK frame parsing picks up a random
byte as the A
field (cipher algorithm). Patch files/0001_agent.patch
fixes this by hard setting padding to -1
, which
seems to be the value held by padding
when using any other non-TPM backed key. As the time of writing, I haven't yet engaged
with upstream community to report the bug so the rogue patch is still part of this repo.