Repository files navigation

A Vagrant file to easily bring up a test Keylime environment using an Ansiblerole to deployKeylime with apre-configured and ready to use TPM Emulator.

For details on using Keylime, please consult the generalproject documentation

⚠Do not use a software TPM emulator in a production environment. ⚠

SELinux is set topermissive for this role.

This role is designed to enable development environment provisioning or to setup a sandbox environment to test drive Keylime.

Should you want to deploy with a hardware TPM, use theanisble-keylime role

The Ansible role may be used on its own.

Run the example playbook against your target remote node(s). For instance:

ansible-playbook -i your_hosts playbook.yml

AVagrantfile is available for provisioning virtual machines for localtesting.

Clone the repository and then simply run with the following additional argsadded to thevagrant command:

• --instances: The number of Keylime virtual machines to create. If notprovided, it defaults to1
• --repo: This is intended to help you hack on Keylime. It mounts a localKeylime Git repository into the virtual machine, allowing you to test your codewithin the VM. This is optional and will mount the repo directory you pass inat "/root/keylime-dev".
• --cpus: The number of CPUs. If not provided, defaults to2
• --memory: The amount of memory to assign. If not provided, defaults to2048
• --qualityoflife: Adds a few extras, such as the Powerline improved bashshell prompt as well as an ls alias (ll for ls -lAh). This is optional.

Deployment example, using libvirt as the virtualization provider:

vagrant --instances=2 --repo=/home/jdoe/keylime --cpus=4 --memory=4096  up --provider libvirt --provision

Deployment example, using VirtualBox as the virtualization provider:

vagrant --instances=2 --repo=/home/jdoe/keylime --cpus=4 --memory=4096  up --provider virtualbox --provision

If you would like to customise these defaults without having to specify them onthe command line each time, you can use avagrant_variables.yml file. Thesimplest way to do this is to copyvagrant_variables.yml.sample tovagrant_variables.yml and edit it:

cp vagrant_variables.yml.sample vagrant_variables.yml

You can still override the defaults invagrant_variables.yml by using thecommand line options.

Once the VM is started, usevagrant ssh to ssh into the VM and runsudo su -to become root.

The TPM emulator will be running.

You can then start the various components using commands:

keylime_verifierkeylime_registrarkeylime_agentkeylime_tenant

Note: you will most likely need to export the right TPM2TOOLS_TCTI environmentvariable before being able to successfully start keylime_agent. To do so:export TPM2TOOLS_TCTI="mssim:port=2321"

A full, step-by-step guide for provisioning a Keylime development setup on Fedora can be foundhere.

If you just want to upgrade Keylime within your VM(s), running the following asroot, from within/root/keylime, should be enough:git pullpython setup.py install

To fully rebuild your VM(s), run the following from the directory where you cloned this repo:vagrant destroyNote: this will delete your Keylime VM(s).

You can then re-deploy the VM(s) by re-running the provisioning step.

Lastly, if you have a VM that was provisioned using an older version of Fedora(say, 31, while the current Vagrantfile will use Fedora 33), you will need toremove the Fedora 31 cloudbase image beforevagrant up --provision willupgrade you to the new version of Fedora, eg:vagrant box remove fedora/31-cloud-base

The web application can be started with the commandkeylime_webapp. If usingVagrant, port 443 will be forwarded from the guest to port 8443 on the host.

This will result in the web application being available at the following URL:

https://localhost:8443/webapp/

This role deploys a basic ima-policy into/etc/ima/ima-policy so that IMArun time integrity may be used. For this to activate, you must reboot themachine first (if you're using vagrant, performvagrant reload)

If for some reason the TPM and IMA emulation aren't working correctly, you canrestart those services with

systemctl restart tpm_emulatorsystemctl restart ima_emulator

To allow direct access to the Keylime components from the host machine, you canforward the ports for the various Keylime components by uncommenting therelevant lines in the Vagrantfile.

Apache2.0

We welcome contributions and pull requests are welcome!

Please ensure CI tests pass!

• Luke Hinds (lhinds@redhat.com)
• Leo Jia (ljia@redhat.com )
• Andrew Stoycos (astoycos@bu.edu)
• Amy Pattanasethanon (raynecarnes@gmail.com)
• axel simon (axel@redhat.com)