Installation¶
There are three current methods for installing Keylime: the Ansible role, the Keylime installer or a manual installation.
Ansible Keylime Roles¶
An Ansible role to deploy Keylime , alongside the Keylime Rust cloud agent
Warning
Please note that the Rust cloud agent is still under early stages of development. Those wishing to test drive Keylimes functionality should use the existing Python based cloud agent keylime_agent until later notice.
This role deploys Keylime for use with a Hardware TPM.
Should you wish to deploy Keylime with a software TPM emulator for development or getting your feet wet, use the Ansible Keylime Soft TPM role instead.
Usage¶
Download or clone Ansible Keylime from its repository and follow the usage section.
Run the example playbook against your target remote host(s):
ansible-playbook -i your_hosts playbook.yml
TPM Version Control (Software TPM)¶
Ansible Keylime Soft TPM provides a role type for 2.0 TPM versions.
TPM 2.0 support can be configured by simply adding the role in the playbook.yml file here
For TPM 2.0 use:
- ansible-keylime-tpm20
This rule uses the TPM 2.0 Emulator (IBM software TPM).
Vagrant¶
If you prefer, a Vagrantfile is available for provisioning.
Clone the repository and then simply run:
vagrant up --provider <provider> --provision
For example, using libvirt:
vagrant up --provider libvirt --provision
For example, using VirtualBox:
vagrant up --provider virtualbox --provision
Once the VM is started, vagrant ssh into the VM and run sudo su - to become root.
You can then start the various components using commands:
keylime_verifier
keylime_registrar
keylime_agent
Rust Cloud agent¶
To start the rust cloud agent, navigate to it’s repository directory and use cargo to run:
[root@localhost rust-keylime]# RUST_LOG=keylime_agent=trace cargo run
Finished dev [unoptimized + debuginfo] target(s) in 0.28s
Running `target/debug/keylime_agent`
INFO keylime_agent > Starting server...
INFO keylime_agent > Listening on http://127.0.0.1:1337
Keylime Bash installer¶
Keylime requires Python 3.7 for dataclasses support.
Installation can be performed via an automated shell script, installer.sh. The following command line options are available:
Usage: ./installer.sh [option...]
Options:
-k Download Keylime (stub installer mode)
-t Create tarball with keylime_agent
-m Use modern TPM 2.0 libraries (vs. TPM 1.2)
-s Install TPM in socket/simulator mode (vs. chardev)
-p PATH Use PATH as Keylime path
-h This help info
Docker - Deployment¶
The verifier, registrar and tenant can also be deployed using Docker images. Keylime’s offical images can be found here. Those are automatically generated for every commit and release.
For building those images locally see here.
Docker - Development¶
Python Keylime and with a TPM emulator can also be deployed using Docker. Since this docker configuration uses a TPM emulator, it should only be used for development or testing and NOT in production.
Please see either the Dockerfiles here or our local CI script here which will automate the build and pull of Keylime.
Manual¶
Keylime requires Python 3.7 or newer to work properly out of the box because older versions do not support dataclasses.
Python-based prerequisites¶
The following Python packages are required:
cryptography>=3.3.2
tornado>=5.0.2
m2crypto>=0.21.1
pyzmq>=14.4
pyyaml>=3.11
simplejson>=3.8
requests>=2.6
sqlalchemy>=1.3
alembic>=1.1.0
python-gnupg>=0.4.6
packaging>=16.0
psutil>=5.4.2
The current list of required packages can be found here.
All of them should be available as distro packages. See installer.sh for more information if you want to install them this way. You can also let Keylime’s setup.py install them via PyPI.
TPM 2.0 Support¶
Keylime uses the Intel TPM2 software set to provide TPM 2.0 support. You will need to install the tpm2-tss software stack (available here) and tpm2-tools utilities available here. See README.md in these projects for detailed instructions on how to build and install.
The brief synopsis of a quick build/install (after installing dependencies) is:
# tpm2-tss
git clone https://github.com/tpm2-software/tpm2-tss.git tpm2-tss
pushd tpm2-tss
./bootstrap
./configure --prefix=/usr
make
sudo make install
popd
# tpm2-tools
git clone https://github.com/tpm2-software/tpm2-tools.git tpm2-tools
pushd tpm2-tools
./bootstrap
./configure --prefix=/usr/local
make
sudo make install
To ensure that you have the recent version installed ensure that you have the tpm2_checkquote utility in your path.
Note
Keylime by default (all versions after 6.2.0) uses the kernel TPM resource manager. For kernel versions older than 4.12 we recommend to use the tpm2-abrmd resource manager (available here).
How the TPM is accessed by tpm2-tools can be set using the TPM2TOOLS_TCTI environment variable. More information about that can be found here.
Talk to the swtpm emulator directly:
export TPM2TOOLS_TCTI="mssim:port=2321"
To talk to the TPM directly (not recommended):
export TPM2TOOLS_TCTI="device:/dev/tpm0"
Install Keylime¶
You’re finally ready to install Keylime:
sudo python setup.py install
Database support¶
Keylime supports the following databases:
* SQLite
* PostgreSQL
* MySQL
* Oracle
* Microsoft SQL Server
SQLite is supported as default.
Each database is configured within /etc/keylime.conf for both the keylime_verifier and keylime_registrar databases.
SQLite¶
The following illustrates examples for SQLite and PostgreSQL:
database_drivername = sqlite
database_username = ''
database_password = ''
database_host = ''
database_port = ''
database_name = cv_data.sqlite
database_query = ''
PostgreSQL¶
For PostgreSQL you will need to install the database first and set up a user account:
database_drivername = postgresql
database_username = keylime
database_password = allyourbase
database_host = localhost
database_port = 5432
database_name = keylime_db
database_query = ''
For details on other platforms, please refer to the SQLAlchemy documentation on engine configuration.