Skip to content

Commit

Permalink
Proposal 50: Learn the IMA keyrings and keys from the log
Browse files Browse the repository at this point in the history
Signed-off-by: Stefan Berger <[email protected]>
  • Loading branch information
stefanberger authored and THS-on committed Sep 25, 2024
1 parent 2a462b6 commit fbde7c6
Showing 1 changed file with 283 additions and 0 deletions.
283 changes: 283 additions & 0 deletions 50-learn-ima-keys.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,283 @@
<!--
**Note:** When your enhancement is complete, all of these comment blocks should be removed.
To get started with this template:
- [ ] **Create an issue in keylime/enhancements**
When filing an enhancement tracking issue, please ensure to complete all
fields in that template. One of the fields asks for a link to the enhancement. You
can leave that blank until this enhancement is made a pull request, and then
go back to the enhancement and add the link.
- [ ] **Make a copy of this template.**
name it `NNNN-short-descriptive-title`, where `NNNN` is the issue number (with no
leading-zero padding) assigned to your enhancement above.
- [ ] **Fill out this file as best you can.**
At minimum, you should fill in the "Summary", and "Motivation" sections.
These should be easy if you've preflighted the idea of the enhancement with the
appropriate SIG(s).
- [ ] **Merge early and iterate.**
Avoid getting hung up on specific details and instead aim to get the goals of
the enhancement clarified and merged quickly. The best way to do this is to just
start with the high-level sections and fill out details incrementally in
subsequent PRs.
-->
# enhancement-50: Learn the keys IMA is using for signature verification

<!--
This is the title of your enhancement. Keep it short, simple, and descriptive. A good
title can help communicate what the enhancement is and should be considered as part of
any review.
-->

<!--
A table of contents is helpful for quickly jumping to sections of a enhancement and for
highlighting any additional information provided beyond the standard enhancement
template.
-->

<!-- toc -->
- [Release Signoff Checklist](#release-signoff-checklist)
- [Summary](#summary)
- [Motivation](#motivation)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Proposal](#proposal)
- [User Stories (optional)](#user-stories-optional)
- [Story 1](#story-1)
- [Story 2](#story-2)
- [Notes/Constraints/Caveats (optional)](#notesconstraintscaveats-optional)
- [Risks and Mitigations](#risks-and-mitigations)
- [Design Details](#design-details)
- [Test Plan](#test-plan)
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
- [Drawbacks](#drawbacks)
- [Alternatives](#alternatives)
- [Infrastructure Needed (optional)](#infrastructure-needed-optional)
<!-- /toc -->

## Release Signoff Checklist

<!--
**ACTION REQUIRED:** In order to merge code into a release, there must be an
issue in [keylime/enhancements] referencing this enhancement and targeting a release**.
For enhancements that make changes to code or processes/procedures in core
Keylime i.e., [keylime/keylime], we require the following Release
Signoff checklist to be completed.
Check these off as they are completed for the Release Team to track. These
checklist items _must_ be updated for the enhancement to be released.
-->

- [ ] Enhancement issue in release milestone, which links to pull request in [keylime/enhancements]
- [ ] Core members have approved the issue with the label `implementable`
- [ ] Design details are appropriately documented
- [ ] Test plan is in place
- [ ] User-facing documentation has been created in [keylime/keylime-docs]

<!--
**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
-->

## Summary

<!--
This section is incredibly important for producing high quality user-focused
documentation such as release notes or a development roadmap. It should be
possible to collect this information before implementation begins in order to
avoid requiring implementers to split their attention between writing release
notes and implementing the feature itself. Reviewers
should help to ensure that the tone and content of the `Summary` section is
useful for a wide audience.
A good summary is probably at least a paragraph in length.
-->

IMA's policy implements support for policy rules that cause keys loaded onto kernel
keyrings to be logged in the IMA measurement log in 'ima-buf' entries. This now
provides the opportunity to also learn the keys that IMA is using for signature verification
from these 'ima-buf' entries, where the DER-encoded public key is reported as part
of the measurement log entry. The learned keys can then be used to verify the
subsequent signatures found in the log.


## Motivation

Recent extensions to Keylime's allowlist (policy) enable Keylime to verify 'ima-buf'
entries similar to verifying file entries and their allowed hashes. If IMA is now
reporting keys loaded onto keyrings then the allowlist must have the corresponding
entries for the keyrings, otherwise the system will fail log verification.
Having these entries in the allowlist implies that the system administrator agrees
to the list of keys being loaded and therefore Keylime can also learn which keys are
used by a given system for signature verification and also use those keys from the
measurement log to verify the signatures itself rather than the administrator having
to provide the keys.

<!--
This section is for explicitly listing the motivation, goals and non-goals of
this enhancement. Describe why the change is important and the benefits to users.
-->

### Goals

<!--
List the specific goals of the enhancement. What is it trying to achieve? How will we
know that this has succeeded?
-->

The goal of this enhancement is to make the management of IMA signature verification
keys easier. Since a system administrator has to provide allowed keys' hashes in
the allowlist already he should not have to provide the IMA signature verification
keys for Keylime to be able to verify file signatures.

### Non-Goals

<!--
What is out of scope for this enhancement? Listing non-goals helps to focus discussion
and make progress.
-->

## Proposal

<!--
This is where we get down to the specifics of what the proposal actually is.
This should have enough detail that reviewers can understand exactly what
you're proposing, but should not include things like API designs or
implementation. The "Design Details" section below is for the real
nitty-gritty.
-->

Based on data from the 'ima-buf' log entries where IMA reports keys loaded
onto a system's keyrings, Keylime will learn which keyrings are in use
on a system and can then model those keyrings and the keys associated with
them. It can then use those keys for signature verification.

The modeled keys and keyrings will be persisted in the database to support
incremental attestation.

### User Stories (optional)

<!--
Detail the things that people will be able to do if this enhancement is implemented.
Include as much detail as possible so that people can understand the "how" of
the system. The goal here is to make this feel real for users without getting
bogged down.
-->

#### Story 1

A system administrator using an IMA policy rule like the following does not
need to manage a system's IMA signature verification keys anymore since Keylime
will learn about the existence of the .ima keyring and the keys loaded onto it.

measure func=KEY_CHECK keyrings=.ima

### Notes/Constraints/Caveats (optional)

<!--
What are the caveats to the proposal?
What are some important details that didn't come across above.
Go in to as much detail as necessary here.
This might be a good place to talk about core concepts and how they relate.
-->

### Risks and Mitigations

<!--
What are the risks of this proposal and how do we mitigate. Think broadly.
For example, consider both security and how this will impact the larger
enhancement ecosystem.
How will security be reviewed and by whom?
-->

## Design Details

<!--
This section should contain enough information that the specifics of your
change are understandable. This may include API specs (though not always
required) or even code snippets. If there's any ambiguity about HOW your
proposal will be implemented, this is the place to discuss them.
-->

The Keyime database will need to be extended with a column for storing
the keyrings and keys learned from the IMA log.
Every time a system is attestated to starting with log entry 0 the previously
learned keyring and keys are discarded since the IMA log is expected to
again report the keyrings and keys.

### Test Plan

<!--
**Note:** *Not required until targeted at a release.*
Consider the following in developing a test plan for this enhancement:
- Will there be e2e and integration tests, in addition to unit tests?
- How will it be tested in isolation vs with other components?
No need to outline all of the test cases, just the general strategy. Anything
that would count as tricky in the implementation and anything particularly
challenging to test should be called out.
All code is expected to have adequate tests (eventually with coverage
expectations).
-->

### Upgrade / Downgrade Strategy

<!--
If applicable, how will the component be upgraded and downgraded? Make sure
this is in the test plan.
Consider the following in developing an upgrade/downgrade strategy for this enhancement
-->

The keylime database will be upgradable and downgradable with an
SQL Alchemy script.

### Dependencie requirements

<!--
If your new change requires new dependencies, please outline and demonstrate that your selected dependency
is well maintained and packaged in Keylime's supported Operating Systems (currently Debian Stable
and as of time writing Fedora 32/33).
During code implementation you will also be expected to add the package to CI , the keylime ansible role and
keylimes main installer (`keylime/installers.sh`).
If the package is not available in the supported Operated systems, the PR will not be merged into master.
Adding the package in `requirements.txt` is not sufficent for master which is where we tag releases from.
You may however be able to work within an experimental branch until a package is made available. If this is
the case, please outline it in this enhancement.
-->

No new dependencies will be introduced.

## Drawbacks

<!--
Why should this enhancement _not_ be implemented?
-->

None known.

## Alternatives

<!--
What other approaches did you consider and why did you rule them out? These do
not need to be as detailed as the proposal, but should include enough
information to express the idea and why it was not acceptable.
-->

If a system administrator does not provide this type of an IMA policy rule then
he/she will have to provide the IMA signature verification keys as before.

## Infrastructure Needed (optional)

<!--
Use this section if you need things infrastructure related specific to your enhancement. Examples include a
new subproject, repos requested, github webhook, changes to CI (travis).
-->

0 comments on commit fbde7c6

Please sign in to comment.