QUICKSTART: Boot with an Enforcer ready kernel, take ownership of your TPM, edit /etc/enforcer/enforcer.db.entries to contain the directories/files you wish to protect. Then run the admin tool: # enforcer-admin all CREATE YOUR DATABASE: For testing purposes, put a small file in /root/ (eg /root/test) and put a couple lines of text in the file. Create a file /etc/enforcer/enforcer.db.entries that has a single line like this action=log /root/test (man enforcer-config for the gory details) Then run: # enforcer-admin builddb This will iterate over /etc/enforcer/enforcer.db.entries and create a database that the kernel module can read in /etc/enforcer/enforcer.db . RUNNING WITH SCISSORS (err, I mean the Enforcer): If you compiled the Enforcer with 'Enforcer debug statements' then it has the ability to print out various amounts of debug info, as well as disable the digital signature normally required on the database. This makes testing easier. A debug level of 1 will print a message to syslog for every file that is checked, as well as some startup and shutdown info. Once you are familiar with what the Enforcer is actually doing you should recompile with the debug option disabled. If you built the Enforcer into the kernel you will need to reboot and pass the following to your boot loader: enforcer.debug_level=1 enforcer.check_signature=no Otherwise load the module: # modprobe enforcer debug_level=1 check_signature=no VERIFYING THE ENFORCER ACTUALLY WORKS: To verify the Enforcer actually works, set up a window tailing your kernel log, usually /var/log/kern.log, and cat the file you set up at the beginning. You should see the contents from the cat. Make a copy of the file: # cp -a /root/test /root/test2 Now, modify the file and try to cat it again. cat will succeed, but you will see an entry like the following in kern.log: kernel: Enforcer:enforcer_bad_entry:1153: Enforcer: attribute mtime of `/root/test' incorrect kernel: Enforcer:enforcer_bad_entry:1182: Enforcer: Expected: 1074028730.768740586 kernel: Enforcer:enforcer_bad_entry:1186: Enforcer: Found: 1078860942.634554050 kernel: Enforcer:enforcer_bad_entry:1204: Enforcer: this means the file has been modified since the database was built. Your system may be compromised. Change the contents of the file back to what they were and cat the file again. Even though the SHA1 now matches its original value you will still not be able to access the file. This is because the mtime (and possibly the inode #) have now been changed. With some trickery you can get the original values back. If you do that (or copy the backup you made earlier), you should be able to cat the file without any problems. If the action of that file includes 'deny', then you will be able to modify the file the from its original state, but not back again. Once the file has been modified, all access is denied. SIGNING THE DATABASE: The first time, you will need to generate a RSA keypair to sign the database with. Do this by running: # enforcer-admin genkey [ Note, for a production system the private key should be moved to some secure location, preferably a removable media with a physical read only toggle. This can be accomplished by passing --secret-base=/secure/location to enforcer-admin. ] To sign a database run: # enforcer-admin signdb This will sign the database with the above generated private key. SETTING UP TCPA INTEGRATION: Take ownership of your TPM and establish a SRK. See your manufacturer's documentation for how to do this. Do not forget your SRK password/secret, you will need it in a minute. When working with IBM's TPM hardware there is a utility in TPM/examples/takeown that will do this. If you installed the Debian libtcpa-dev package this will be available as /usr/lib/libtcpa1.1/examples/takeown . Install the TCPA enabled LILO, available from the Enforcer SourceForge page under 'LILO w/TCPA Support'. Follow the directions from the package's README for booting with the TCPA enabled LILO. Reboot the system with the TCPA LILO and the Enforcer enabled kernel. This will set up PCRs 0-10 of the TPM's with the current values for the currently running system. The kernel is hashed into PCR #9, your public key (/etc/enforcer/key.pub) is hashed into PCR #10, and your LILO MBR and second stage are hashed into PCR #8. If you change any of these you will need to reboot to set up the PCRs and then reseal your secret to the new PCRs. Create and bind a secret to be used to mount the encrypted loopback file system: # enforcer-admin seal This will prompt you for the SRK password you set above, and for a data password. Pick anything for the data password. The SRK and data passwords will be written to /etc/enforcer/tcpa.pw . Storing these passwords on disk in plaintext is not as bad as it seems. The Enforcer/TCPA security comes from the integrity of the running software, hence the values of the PCRs, not the secret used inside the TPM. The worse anyone with the SRK and root privileges can do is to bind a new secret into a new data blob. This does not invalidate or compromise any previously bound secrets. If necessary an Enforcer specific GPG keypair will be generated and the secret will be exported from the TPM and encrypted with the GPG key. This will allow you to keep a protected backup of the secret. Reboot (or modprobe both the enforcer and IBM's tpm module if the Enforcer is a module) and you should see a lines similar to the following in /var/log/kern.log when the Enforcer loads: kernel: Enforcer:enforcer_verify_db_sig: TPM Unseal operation successful, secret accessible. kernel: Enforcer:enforcer_verify_db_sig: database (/etc/enforcer/enforcer.db) signature verified. kernel: Enforcer:enforcer_setup: database loaded, 15072 entries. Those lines indicate the system is up and running, the hardware, BIOS, boot loader, and kernel are the ones the security admin set up for the TPM, the public key is the one used to sign the databases, and the Enforcer module is successfully running. If you are using a debugging version of the Enforcer you will also see likes like these in your kernel log: kernel: Enforcer:enforcer_verify_db_sig: enforcer_tcpa_useal result is 128 bytes long. If the enforcer is a module, you need to pass the flag extend=no for every modprobe but the first. UPGRADING THE SYSTEM: Since you now have tamper detection running, upgrading has a few new steps. First, reboot (preferably via a serial console with the network disabled), add the following parameter to the boot line 'enforcer.active=no'. This will prevent the Enforcer from loading. Upgrade your system, regenerate the database, re-sign the database, and reboot. The database can be rebuilt and re-signed using the admin tool: # enforcer-admin db UPGRADING YOUR KERNEL (or changing you public key): Sorry, upgrading is not currently automated. After you upgrade your kernel and reboot (to setup the PCRs), reseal your secret into the TPM and reboot again. Your secret can be imported using the admin tool: # enforcer-admin importsecret HELPER / ENCRYPTED LOOPBACK If you want to use the TPM to protect a loopback encryption key and automatically mount that file system on boot, see the document README.HELPER. PROJECT HOME PAGE: