TPM Keyring - Quickstart Guide

Send questions and comments to: kyoder@users.sf.net.

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.

Build

$ {yast2 -i|yum install|emerge} python-devel swig qt3-devel openssl-devel gtk2-devel
$ cvs -d:pserver:anonymous@trousers.cvs.sourceforge.net:/cvsroot/trousers co trousers
$ cd trousers
$ sh bootstrap.sh
$ ./configure && make
# make install
$ cd ..
$ cvs -d:pserver:anonymous@trousers.cvs.sourceforge.net:/cvsroot/trousers co applications/tpm_keyring2
$ cd applications/tpm_keyring2
$ make
# make install

Setup

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.

Run

# /usr/local/sbin/tcsd
$ tpm_keyring

Tutorial

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.

 [toki@toki.dethklok.com]$ 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.

Backups

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 toki@dethklok.com

Send questions and comments to: kyoder@users.sf.net.