TPM Keyring - Quickstart Guide

May 10, 2007 WARNING: Right now, eCryptfs and TrouSerS aren't working together. Changes in the eCryptfs PKI API keep the TSS patch from applying, and I haven't updated the patch yet. Sorry for the inconvenience.

Send questions and comments to:

TPM Keyring is intended as a key manager for TPM-based keys used in eCryptfs. For a guide to installing eCryptfs, go here.

Once a group is set up to share a key, all the members of the group can securely exchange files using any method they like. The creator of the group can control who becomes a member of the group and members cannot redistribute the key.

Note that keeping members from re-distributing the key hinges on the fact that all members of the group have a real TPM. If any member can join the group using a software TPM, he can recover the private key and distribute it widely.


Before you can use your TPM with any application, there are some setup steps that need to be made. First, you'll need to enable your TPM in your BIOS. Most machines with TPMs ship with the TPM disabled by default, so this is usually a requirement.

Secondly, you will need to take ownership of the chip using the tpm-tools package. When you take ownership of the chip, you will need to provide 2 new passwords, the owner password and the Storage Root Key (SRK) password. Whenever you load a key into the TPM, the SRK password must be given. The owner password is for adminstration and other sensitive tasks only. Since the eCryptfs TPM code prompts you using the TSS GUI popup for your SRK password when its time to decrypt your files, you need to tell tpm-tools to use a unicode password when taking ownership, like this:

$ tpm_takeownership -u

This is because TSS popups always convert their passwords to unicode after being entered (this is mandated by the TSS spec). If you've already taken ownership using a non-unicode password, you can change the SRK password to unicode using this command:

$ tpm_changeownerauth -s -n


$ {yast2 -i|yum install|emerge} python-devel swig qt3-devel openssl-devel gtk2-devel
$ cvs co trousers
$ cd trousers
$ sh
$ ./configure && make
# make install
$ cd ..
$ cvs co applications/tpm_keyring2
$ cd applications/tpm_keyring2
$ make
# make install


If you'd like to allow others to add you to a group they've created, you'll need to allow remote connections to be accepted by your TrouSerS TCS daemon. They'll need the following operations enabled in /usr/local/etc/tcsd.conf:
#                   getpubkey - Retrieve a loaded key's public data from inside the TPM
#                   selftest - execute selftest and test results ordinals
# remote_ops =

remote_ops = registerkey,loadkey,random,getpubkey

You should co-ordinate with your friends so that you don't have to enable remote operations for long periods of time. Keeping the TCS daemon from accepting remote connections closes one more possible vector of attack from outside your firewall. To turn off remote connections, just comment out the "remote_ops" line and re-start your TCS daemon.


# /usr/local/sbin/tcsd
$ tpm_keyring


Click the "Add Group" button and enter a name for your group, select a key size (these are RSA key sizes in bits) and enter a password for the software key.


After creating a group, a software copy of the key is stored on disk (encrypted with the password you gave it) in the ~/.tpmkeyring2 directory. Also, a copy of this key has been wrapped by your TPM and stored in your user persistent store by TrouSerS.

Now, you'll want to distribute this key to your friends, right?


Add a nick name for your friend, and the host name or IP address of your friend's box. Hit 'OK' and you'll see a new row in the member's table for your friend:

You can add as many friends as you want:


You'll be prompted for your friend's SRK password if he requires one:

Hit the blue play button to attempt to send the key to your friend. This will wrap the group's software key using your friend's TPM and store it in his system persistent storage. This will require that he sets up his TCS daemon to allow remote connections and store keys, just as you did in the Setup step.

Once your friend has been successfully added to the group, a green check mark appears next to his name:


The user you've added to the group now needs to bring up tpm_keyring and import the key you've stored into his user persistent store.

 []$ tpm_keyring


He'll see the group name and key size, but the group will be marked as imported in his combobox. Notice that he cannot add any new members to the group. This is because the only copy of the key that he has is wrapped by his TPM. Instead of a list of remote members to the group, he'll see 'me' and the UUID of the key he's imported.


You're going to want to make backups of your keys, whether you're the creator of any groups or not. However, if you lose an imported key the creator of the group can always re-add you.

Once you've added everyone you want to add to a group, you should move the software key off the machine you're using:

$ mv ~/.tpmkeyring2/*.pem /media/usb

Now go lock that usb key in a safe...

Mounting eCryptfs

Now, how do you use these keys you've wrapped? You'll need to mount eCryptfs using the TPM PKI, pointing the mount to your group's wrapped key in user persistent storage. First, right click the member's list to copy the key's UUID into the clipboard:

Now, there's only one problem left to solve before this all works smoothly. You'll most likely need to start the ecryptfsd as root, but you need it to have access to the tpm keys that are stored in your $(HOME)/.tpmkeyring2 directory. So, you'll need to set an environment variable to point the ecryptfs daemon at the right data store. This is what the export TSS_USER_PS_FILE= line does below:

# mkdir -p /ecryptfs/upper
# mkdir -p /ecryptfs/lower
# modprobe ecryptfs
# export TSS_USER_PS_FILE=/home/YOUR_USERNAME/.tpmkeyring2/tpmkeyring2_tpm_keys
# ecryptfsd
# mount -t ecryptfs /ecryptfs/lower /ecryptfs/upper -o key=tpm:uuid=a79afba5247b1169f1f50f972031cb4b

You can now copy files into the eCryptfs mount and they'll be transparently encrypted using a per-file random key that's wrapped by your group's RSA key:

$ mv /media/video/* /ecryptfs/upper

There isn't yet a good way to keep your eCryptfs upper and lower filesystems in sync, or to retrieve the ciphertext of an eCryptfs file through the upper mount. So, to copy out the ciphertext to send to our group, you'll have to unmount eCryptfs:

# umount /ecryptfs/upper

You can now share the encrypted files in your lower directory with anyone in the same group securely, no matter how you distribute them:

$ mail -a /ecryptfs/lower/copyrighted_material.tar.bz2

Send questions and comments to: Logo