From e1004e36e949b73991d7d672fa31303437c51de9 Mon Sep 17 00:00:00 2001 From: Luke Hinds Date: Fri, 12 Apr 2019 19:01:26 +0100 Subject: [PATCH] Flesh out body of documentation --- README.md | 8 + docs/certificate_authority.rst | 3 - docs/developers.rst | 108 ++++++++++++- docs/index.rst | 5 +- docs/installation.rst | 277 +++++++++++++++++++++++++++++++++ docs/security.rst | 13 ++ 6 files changed, 405 insertions(+), 9 deletions(-) delete mode 100644 docs/certificate_authority.rst diff --git a/README.md b/README.md index 58ee37f02..84bc9a02b 100644 --- a/README.md +++ b/README.md @@ -1 +1,9 @@ # keylime-docs + +[![Documentation Status](https://readthedocs.org/projects/keylime-docs/badge/?version=latest)](https://keylime-docs.readthedocs.io/en/latest/?badge=latest) + +All Keylime documentation is formatted in [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText) + +The documentation project is built using [sphinx](http://www.sphinx-doc.org) + +Documentation is hosted on [readthedocs](https://readthedocs.org/) diff --git a/docs/certificate_authority.rst b/docs/certificate_authority.rst deleted file mode 100644 index 276617cd1..000000000 --- a/docs/certificate_authority.rst +++ /dev/null @@ -1,3 +0,0 @@ -==================== -Certificate Authority -==================== diff --git a/docs/developers.rst b/docs/developers.rst index 70696cfde..12b298320 100644 --- a/docs/developers.rst +++ b/docs/developers.rst @@ -1,3 +1,105 @@ -========== -Developers -========== +=================== +KeyLime Development +=================== + +Contributing +------------ + +When contributing to this repository, please first discuss the change you wish +to make via an issue in the relevant repository for your change or email to the +[keylime mailing list](https://groups.io/g/keylime). + +## Pull Request Process + +1. Create an [issue](https://github.com/keylime/python-keylime/issues) + outlining the fix or feature. +2. Fork the keylime repository to your own github account and clone it locally. +3. Hack on your changes. +4. Update the README.md or documentation with details of changes to any + interface, this includes new environment variables, exposed ports, useful + file locations, CLI parameters and configuration values. +5. Add and commit your changes with some descriptive text on the nature of the + change / feature in your commit message. Also reference the issue raised at + [1] as follows: `Fixes #45`. See [here](https://help.github.com/articles/closing-issues-using-keywords/) + for more message types +6. Ensure that CI passes, if it fails, fix the failures. +7. Every pull request requires a review from the [core keylime team](https://github.com/orgs/keylime/teams/core) + +Docker Development Environment +------------------------------ + +The following is a guide to mounting your local repository as a Docker volume +and performing a test run using a TPM simulator. This will replicate the same +test that occurs within the KeyLime CI gate for python-KeyLime + +* ToDo: Also run rust checks + +This requires a working installation of Docker. See your distributions guide on +how to set that up. + +As an example, on Fedora 29: + +``` +sudo dnf -y install dnf-plugins-core +sudo dnf install docker-ce docker-ce-cli containerd.io +sudo usermod -aG docker $USER +sudo systemctl enable docker +sudo systemctl start docker +``` + +Note: login and out of your shell, if you want to run docker as `$USER` + +Save the following script to your local machine (tip: create an alias to call the +script in an easy to remember way) + +``` +#!/bin/bash + +# Your local python-keylime (you should likely change this) +REPO="/home/${USER}/python-keylime" + +# keylime images +tpm12image="lukehinds/keylime-ci-tpm12" +tpm12tag="v300" +tpm20image="lukehinds/keylime-ci-tpm20" +tpm20tag="v301" + +echo -e "Grabbing latest images" + +docker pull ${tpm12image}:${tpm12tag} +docker pull ${tpm20image}:${tpm20tag} + +function tpm1 { + container_id=$(mktemp) + docker run --detach --privileged \ + -v $REPO:/root/python-keylime \ + -it ${tpm12image}:${tpm12tag} >> ${container_id} + docker exec -u 0 -it --tty "$(cat ${container_id})" \ + /bin/sh -c 'cd /root/python-keylime/test; chmod +x ./run_tests.sh; ./run_tests.sh -s openssl' + docker stop "$(cat ${container_id})" + docker rm "$(cat ${container_id})" +} + +function tpm2 { + container_id=$(mktemp) + docker run --detach --privileged \ + -v $REPO:/root/python-keylime \ + -v /sys/fs/cgroup:/sys/fs/cgroup:ro \ + -it ${tpm20image}:${tpm20tag} >> ${container_id} + docker exec -u 0 -it --tty "$(cat ${container_id})" \ + /bin/bash /root/python-keylime/.ci/test_wrapper.sh + docker stop "$(cat ${container_id})" + docker rm "$(cat ${container_id})" +} + +while true; do + echo -e "" + read -p "Do you wish to test against TPM1.2(a) / TPM 2.0(b) or q(quit): " abq + case $abq in + [a]* ) tpm1;; + [b]* ) tpm2;; + [q]* ) exit;; + * ) echo "Please answer 1, 2 q(quit)";; + esac +done +``` diff --git a/docs/index.rst b/docs/index.rst index d20229740..1f86e774d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,8 +11,8 @@ nodes using a hardware based cryptographic root of trust. Keylime was originally born out of the security research team in MIT's Lincoln Laboratory and is not developed and maintained by the Keylime community. -This Documentation site contains user guides to install, use and adminster -keylime as well as guides to enable developers to make contributions to keylime +This Documentation site contains guides to install, use and administer keylime +as well as guides to enable developers to make contributions to keylime or develop services against Keylimes Rest API(s). @@ -23,7 +23,6 @@ or develop services against Keylimes Rest API(s). installation user_guide rest_apis - certificate_authority developers security diff --git a/docs/installation.rst b/docs/installation.rst index 6393b5b59..55d4e2e51 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,3 +1,280 @@ ============ Installation ============ + +There are two current methods for installing Keylime, an ansible role, the +keylime installer or a manual installation. + +Ansible Keylime +--------------- + +Download or clone [Ansible Keylime](https://github.com/keylime/ansible-keylime) +from its repository. + +This Ansible role to deploy [Python Keylime](https://github.com/keylime/python-keylime) +and a TPM Emulator, alongside the [Keylime rust cloud node](https://github.com/keylime/rust-keylime). + +Please note that the rust cloud node is still under early stages of Development. +Those wishing to test drive keylimes functionality should use the existing +python based cloud node `keylime_node` until later notice. + +The TPM Emulator should never be used ina production scenario. + +Usage +----- + +Run the example playbook against your target remote node(s). + +``` +ansible-playbook -i your_hosts playbook.yml +``` + +TPM Version Control +------------------- + +Either TPM version 1.2 or TPM 2.0 support can be configured by simply changing +the role in the `playbook.yml` file [here](https://github.com/keylime/ansible-keylime/blob/master/playbook.yml#L11). + +For TPM 2.0 use: + +``` + - ansible-keylime-tpm20 +``` + +For TPM 1.20 use: + +``` + - ansible-keylime-tpm12 +``` + +Both roles will deploy the relevant TPM 1.2 Emulator (tpm4720) or 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 --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_node +``` + +WebApp +------ + +The web application can be started with the command `keylime_webapp`. If using +Vagrant, port 443 will be forwarded from the guest to port 8443 on the host. + +This will result in the web application being available on url: + +https://localhost:8443/webapp/ + +Rust Cloud node +--------------- + +To start the rust cloud node, navigate to it's repository directory and use +cargo to run: + +``` +[root@localhost rust-keylime]# RUST_LOG=keylime_node=trace cargo run + Finished dev [unoptimized + debuginfo] target(s) in 0.28s + Running `target/debug/keylime_node` + INFO keylime_node > Starting server... + INFO keylime_node > Listening on http://127.0.0.1:1337 +``` + +Keylime Bash installer +---------------------- + +Keylime requires Python 2.7.10 or newer for proper TLS 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) +-o Use OpenSSL instead of CFSSL +-t Create tarball with keylime_node +-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 +``` + +Note that CFSSL is required if you want to support revocation. As noted above, do not use +the TPM emulator option `-s` in production systems. + +### Docker (Development Only) + +Python keylime and related emulators can also be deployed using Docker. +Since this docker configuration currently uses a TPM emulator, +it should only be used for development or testing and NOT in production. + +Please see either the Dockerfiles +[here](https://github.com/keylime/python-keylime/tree/master/docker) or our +local CI script +[here](https://github.com/keylime/python-keylime/blob/master/.ci/run_local.sh) +which will automate the build and pull of keylime on TPM 1.2 or 2.0. + +### Manual + +Keylime requires Python 2.7.10 or newer for proper TLS support. This is newer than +some LTS distributions like Ubuntu 14.04 or CentOS 7. See google for instructions +on how to get a newer Python onto those platforms. + +#### Python-based prerequisites + +The following python packages are required: + +* pycryptodomex>=3.4.1 +* tornado>=4.3 +* m2crypto>=0.21.1 +* pyzmq>=14.4 +* setuptools>=0.7 +* python-dev +* pyyaml + +The latter of these are usually available as distro packages. See [installer.sh](https://github.com/keylime/python-keylime/blob/master/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 1.2 Support +~~~~~~~~~~~~~~~ + +You also need a patched version of tpm4720 the IBM software TPM emulator and +utilities. This is available at https://github.com/keylime/tpm4720-keylime. +Even if you are using keylime with a real TPM, you must install the IBM emulator +because keylime uses the command line utilities that come with it. +See README.md in that project for detailed instructions on how to build and install it. + +The brief synopsis of a quick build/install (after installing dependencies) is: + +```bash +git clone https://github.com/keylime/tpm4720-keylime.git +cd tpm4720-keylime/libtpm +./comp-chardev.sh +sudo make install +``` + +To build tpm4720 to use the TPM emulator replace `./comp-chardev.sh` with `./comp-sockets.sh`. + +To ensure that you have the patched version installed ensure that you have +the `encaik` utility in your path. + +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 at +https://github.com/tpm2-software/tpm2-tss) as well as a patched version of the +tpm2-tools utilities available at https://github.com/keylime/tpm2-tools. 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: + +```bash +git clone https://github.com/tpm2-software/tpm2-tss.git tpm2-tss +pushd tpm2-tss +./bootstrap +./configure --prefix=/usr +make +sudo make install +popd + +git clone https://github.com/keylime/tpm2-tools.git tpm2-tools +pushd tpm2-tools +./bootstrap +./configure --prefix=/usr/local +make +sudo make install +``` + +To ensure that you have the patched version installed ensure that you have +the `tpm2_checkquote` utility in your path. + +TPM 2.0 Resource Manager +~~~~~~~~~~~~~~~~~~~~~~~~ + +Note that it is recommended that you use the tpm2-abrmd resource manager +(available at https://github.com/tpm2-software/tpm2-abrmd) as well instead of +communicating directly with the TPM. See README.md at that project for +detailed instructions on how to build and install. + +A brief, workable example for Ubuntu 18 LTS systems is: + +```bash +sudo useradd --system --user-group tss +git clone https://github.com/tpm2-software/tpm2-abrmd.git tpm2-abrmd +pushd tpm2-abrmd +./bootstrap +./configure --with-dbuspolicydir=/etc/dbus-1/system.d \ + --with-systemdsystemunitdir=/lib/systemd/system \ + --with-systemdpresetdir=/lib/systemd/system-preset \ + --datarootdir=/usr/share +make +sudo make install +sudo ldconfig +sudo pkill -HUP dbus-daemon +sudo systemctl daemon-reload +sudo service tpm2-abrmd start +export TPM2TOOLS_TCTI="tabrmd:bus_name=com.intel.tss2.Tabrmd" + +# NOTE: if using swtpm2 emulator, you need to run the tpm2-abrmd service as: +sudo -u tss /usr/local/sbin/tpm2-abrmd --tcti=mssim & +``` + +Alternatively, it is also possible, though not recommended, to communicate +directly with the TPM (and not use a resource manager). This can be done by +setting the environment var `TPM2TOOLS_TCTI` to the appropriate value: + +To talk directly to the swtpm2 emulator: `export TPM2TOOLS_TCTI="mssim:port=2321"` + +To talk directly to a real TPM: `export TPM2TOOLS_TCTI="device:/dev/tpm0"` + +#### Install Keylime + +You're finally ready to install keylime! +```bash +sudo python setup.py install +``` + +To run on OSX 10.11+ +--------------------- + +You need to build m2crypto from source with + +```bash +brew install openssl +git clone https://gitlab.com/m2crypto/m2crypto.git +python setup.py build build_ext --openssl=/usr/local/opt/openssl/ +sudo -E python setup.py install build_ext --openssl=/usr/local/opt/openssl/ +``` + +#### Optional Requirements + +If you want to support revocation, you also need to have cfssl installed and in your +path on the tenant node. It can be obtained from https://github.com/cloudflare/cfssl. You +will also need to set ca_implementation to "cfssl" instead of "openssl" in `/etc/keylime.conf`. diff --git a/docs/security.rst b/docs/security.rst index 54ee478eb..50c3de570 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -1,3 +1,16 @@ ================ Securing Keylime ================ + +System Hardening +---------------- + +TLS configuration +---------------- + +Reporting an issue +------------------ + +Please contact us directly at security@keylime.groups.io for any bug that might +impact the security of this project. Do not use a github issue to report any +potential security bugs.