Improving the Keylime documentation

[THS-on]

The Keylime documentation is now part of the main repository and want to improve it. Following things need to be improved:

How to use the TPM EK CA Store

There is currently no documentation on how to add custom CA to the cert store (there is only a comment in the keylime.conf).

• Add documentation where the cert store is located and which format is used
• Add list of certificates provided by Keylime
• Describe were to find the most common CAs. (Maybe use https://github.com/Lernstick/Lernstick-Bridge/blob/517ba2c7941c4ba74a30272b9f05e66e06a875cb/tpm_cert_store/README.md as reference)

Supported TPM Configurations

See #1105.

Keylime and virtualized TPMs

The Keylime test setup using the IBM TPM emulator does not have a EK certificate. We should provide documentation on how to add a EK CA and EK certficate for testing. Also there is no documentation on how to use Keylime with virtualized TPMs.

• Add tutorial on how to add an EK certificate to the tpm_emulator using createekcert from the IBM TSS.
• Add tutorial on how to use the libvrit swtpm integration and link to the general swtpm documentation.
• Investigate vTPM implementations of Hyper-V and VMWare

IMA Validation

Keylime does support validation for many of the features provided by IMA. Unfortunately only the basic features are documented.

• Document signature validation against a provided keyring
• Document automatic IMA key learning (@stefanberger ?)
• Document device mapper integration (@THS-on)
• Add tutorial and how to create custom IMA policies using the new format
• Remove references to old format once IMA policy enhancement proposal enhancements#71 is implemented

Measured Boot Validation

Keylime does provide a entire policy engine for measured boot. The current documentation only describes the general concept and not how to use it.

• Add documentation on how to use the example policy and how to use create_mb_refstrate.
• Add documentation on the components to build a policy (@maugustosilva ?)
  • Add section about pitfalls when evaluating the measured boot log (e.g. https://github.com/google/go-attestation/blob/master/docs/event-log-disclosure.md)
  • Add general overview what information can be found the event log

Keylime mTLS setup

The verifier/tenant connects to the agent using mTLS. The entire TLS setup is pretty complicated and will be simplified with keylime/enhancements#73. The following things should be documented:

• How to deploy the agent using the current configuration (@THS-on)
• Describe more complex setups

How to create runtime policies

Add documentation on how to get the information required to create policies.

• Create list of information that is required before creating policies
• IMA signature verification from a distribution that support it
• Get file hashes from deb and RPM repositories
• How to work with containers

Migration guide from older versions

• How to handle DB updates. If auto migration was disabled, you can use alembic stamp to set the correct version and re enable from there
• config upgrades

PR Template

• Create a PR template that contains a reminder to also update the documentation.

[maugustosilva]

#1050 should start to address itens one and two on you list @THS-on. Remember, it is a working in progress, and so it will constantly refined.

[nishitiwari22]

Is this issue still open? I am looking to contribute to it.

[mpeters]

@nishitiwari22 yes absolutely. If you would like to take a topic that's listed here and try it out and then improve the documentation (and feel free to ask any questions you'd like in our slack channel), your contributions would be very welcome!