Skip to content

Commit 06ea7ab

Browse files
THS-onTHS-on
committed
add IMA policy enhancement proposal
Signed-off-by: Thore Sommer <[email protected]>
1 parent 9610bf2 commit 06ea7ab

File tree

1 file changed

+360
-0
lines changed

1 file changed

+360
-0
lines changed

‎70_ima_policy.md

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
<!--
2+
**Note:** When your enhancement is complete, all of these comment blocks should be removed.
3+
4+
To get started with this template:
5+
6+
- [ ] **Create an issue in keylime/enhancements**
7+
When filing an enhancement tracking issue, please ensure to complete all
8+
fields in that template. One of the fields asks for a link to the enhancement. You
9+
can leave that blank until this enhancement is made a pull request, and then
10+
go back to the enhancement and add the link.
11+
- [ ] **Make a copy of this template.**
12+
name it `NNNN-short-descriptive-title`, where `NNNN` is the issue number (with no
13+
leading-zero padding) assigned to your enhancement above.
14+
- [ ] **Fill out this file as best you can.**
15+
At minimum, you should fill in the "Summary", and "Motivation" sections.
16+
These should be easy if you've preflighted the idea of the enhancement with the
17+
appropriate SIG(s).
18+
- [ ] **Merge early and iterate.**
19+
Avoid getting hung up on specific details and instead aim to get the goals of
20+
the enhancement clarified and merged quickly. The best way to do this is to just
21+
start with the high-level sections and fill out details incrementally in
22+
subsequent PRs.
23+
-->
24+
# enhancement-70: Merge allow and exclude list into an IMA policy
25+
26+
<!--
27+
This is the title of your enhancement. Keep it short, simple, and descriptive. A good
28+
title can help communicate what the enhancement is and should be considered as part of
29+
any review.
30+
-->
31+
32+
<!--
33+
A table of contents is helpful for quickly jumping to sections of a enhancement and for
34+
highlighting any additional information provided beyond the standard enhancement
35+
template.
36+
-->
37+
38+
<!-- toc -->
39+
- [Release Signoff Checklist](#release-signoff-checklist)
40+
- [Summary](#summary)
41+
- [Motivation](#motivation)
42+
- [Goals](#goals)
43+
- [Non-Goals](#non-goals)
44+
- [Proposal](#proposal)
45+
- [User Stories (optional)](#user-stories-optional)
46+
- [Story 1](#story-1)
47+
- [Story 2](#story-2)
48+
- [Notes/Constraints/Caveats (optional)](#notesconstraintscaveats-optional)
49+
- [Risks and Mitigations](#risks-and-mitigations)
50+
- [Design Details](#design-details)
51+
- [Test Plan](#test-plan)
52+
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
53+
- [Drawbacks](#drawbacks)
54+
- [Alternatives](#alternatives)
55+
- [Infrastructure Needed (optional)](#infrastructure-needed-optional)
56+
<!-- /toc -->
57+
58+
## Release Signoff Checklist
59+
60+
<!--
61+
**ACTION REQUIRED:** In order to merge code into a release, there must be an
62+
issue in [keylime/enhancements] referencing this enhancement and targeting a release**.
63+
64+
For enhancements that make changes to code or processes/procedures in core
65+
Keylime i.e., [keylime/keylime], we require the following Release
66+
Signoff checklist to be completed.
67+
68+
Check these off as they are completed for the Release Team to track. These
69+
checklist items _must_ be updated for the enhancement to be released.
70+
-->
71+
72+
- [ ] Enhancement issue in release milestone, which links to pull request in [keylime/enhancements]
73+
- [ ] Core members have approved the issue with the label `implementable`
74+
- [ ] Design details are appropriately documented
75+
- [ ] Test plan is in place
76+
- [ ] User-facing documentation has been created in [keylime/keylime-docs]
77+
78+
<!--
79+
**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
80+
-->
81+
82+
## Summary
83+
84+
This enhancement proposal changes and unifies the IMA configuration options by
85+
formally specifying a JSON schema. The tenant and verifier are modified to use
86+
the IMA policy instead of the old flat file format to simplify the process and
87+
allow further development like server side signature validation.
88+
89+
For users of the old flat file format a upgrade path using a commandline tool
90+
will be provided.
91+
92+
## Motivation
93+
94+
The configuration for IMA validation is currently split over multiple options
95+
and is not well documented. This makes it confusing to use and hard to implement
96+
features like signature validation or storing all the information in a separate
97+
DB table to reuse.
98+
99+
### Goals
100+
101+
* Merge the current allow and exclude list into one single JSON object
102+
* Move `ima_sign_verification_keys` also into the JSON object
103+
* Deprecate flat file allow and exclude list
104+
* Simplify IMA related options in the tenant
105+
* Provide a tool for converting flat file allow and exclude list to JSON object
106+
* Convert the `create_allowlist` script to create a `ima_policy`.
107+
108+
### Non-Goals
109+
110+
* Change the current behavior of the IMA validation
111+
* Change how the measured boot reference state works
112+
* Implement server side signature validation
113+
114+
## Proposal
115+
116+
The entries `ima_sign_verification_keys` and `allowlist` will be replaced with
117+
`ima_policy` in the verifier API. `ima_policy` takes a JSON object that contains
118+
all the required data for IMA validation. A schema for the JSON object will be
119+
provided in the Keylime repository.
120+
121+
The `allowlist*` options in the tenant will be renamed to `ima_policy*`.
122+
123+
The flat file format will be deprecated in favor of the JSON format. This is
124+
done to simplify future development like server side signature validation. For
125+
users of the old format a conversion tool will be provided.
126+
127+
128+
### User Stories
129+
130+
#### Story 1a - Using the legacy flat file format
131+
* User generates a allowlist `ima_allowlist.txt` and a exclude list `exclude.txt`
132+
* Conversion to new JSON format with `keylime_convert_allowlist --allowlist ima_allowlist.txt --exclude exclude.txt --out ima_policy.json`
133+
* The conversion tool produces `ima_policy.json`
134+
* Adds a new agent with `keylime_tenant -c add --ima_policy ima.json ...`
135+
* Agent is added to attestation.
136+
137+
#### Story 1b - Using the legacy flat file format with signature
138+
* User generates a allowlist `ima_allowlist.txt` and a exclude list
139+
`exclude.txt`, allowlist signature `ima_allowlist.txt.sig` and the public key `allowlist.key`
140+
* Conversion to new JSON format with `keylime_convert_allowlist --allowlist ima_allowlist.txt --exclude exclude.txt --allowlist-sig ima_allowlist.txt.sig --allowlist-sig allowlist.key --out ima_policy.json`
141+
* The conversion tool validates the signature and produces `ima_policy.json`
142+
* Adds a new agent with `keylime_tenant -c add --ima_policy ima.json ...`
143+
* Agent is added to attestation.
144+
145+
146+
Note that in this case the signature is checked by the conversion tool and that
147+
the exclude list does not have a signature that can be validated. This is fine
148+
because the signature validation is currently only done locally.
149+
150+
151+
#### Story 2a - Using a JSON policy
152+
* User generates a IMA JSON policy called `ima.json`
153+
* Adds a new agent with `keylime_tenant -c add --ima_policy ima.json ...`
154+
* Agent is added to attestation.
155+
156+
#### Story 2b - Using a JSON policy with signature
157+
* User generates a IMA JSON policy called `ima.json` and has a signature
158+
`ima.json.sig` and a public key `policy.key`.
159+
* Adds a new agent with `keylime_tenant -c add --ima_policy ima.json --ima-policy-sig ima.json.sig --ima-policy-sig-key policy.key ...`
160+
* Agent is added to attestation.
161+
162+
163+
### Notes/Constraints/Caveats
164+
165+
* This only affects the server side API of the verifier. Therefore we will not
166+
implement backwards compatibility for older tenant versions.
167+
* Signature validation in the tenant will be only possible with the JSON schema.
168+
169+
### Risks and Mitigations
170+
171+
There are no new risks because we are just unifying the existing configuration
172+
options.
173+
174+
## Design Details
175+
176+
### New IMA policy JSON schema
177+
The IMA policy is formally specified as:
178+
```json
179+
{
180+
"$schema": "https://json-schema.org/draft/2020-12/schema",
181+
"title": "Keylime IMA policy",
182+
"type": "object",
183+
"properties": {
184+
"meta": {
185+
"type": "object",
186+
"properties": {
187+
"version": {
188+
"type": "integer",
189+
"description": "Version number of the IMA policy schema"
190+
}
191+
},
192+
"required": ["version"],
193+
"additionalProperties": false
194+
},
195+
"release": {
196+
"type": "number",
197+
"title": "Release version",
198+
"description": "Version of the IMA policy (arbitrarily chosen by the user)"
199+
},
200+
"digests": {
201+
"type": "object",
202+
"title": "File paths and their digests",
203+
"patternProperties": {
204+
".*": {
205+
"type": "array",
206+
"title": "Path of a valid file",
207+
"items": {
208+
"type": "string",
209+
"title": "Hash of an valid file"
210+
}
211+
}
212+
}
213+
},
214+
"excludes": {
215+
"type": "array",
216+
"title": "Excluded file paths",
217+
"items": {
218+
"type": "string",
219+
"format": "regex"
220+
}
221+
},
222+
"keyrings": {
223+
"type": "object",
224+
"patternProperties": {
225+
".*": {
226+
"type": "string",
227+
"title": "Hash of the content in the keyring"
228+
}
229+
}
230+
},
231+
"ima-buf": {
232+
"type": "object",
233+
"title": "Validation of ima-buf entries",
234+
"patternProperties": {
235+
".*": {
236+
"type": "string",
237+
"title": "Hash of the ima-buf entry"
238+
}
239+
}
240+
},
241+
"verification-keys": {
242+
"type": "array",
243+
"title": "Public keys to verify IMA attached signatures",
244+
"items": {
245+
"type": "string"
246+
}
247+
},
248+
"ima": {
249+
"type": "object",
250+
"title": "IMA validation configuration",
251+
"properties": {
252+
"ignored_keyrings": {
253+
"type": "array",
254+
"title": "Ignored keyrings for key learning",
255+
"description": "The IMA validation can learn the used keyrings embedded in the kernel. Use '*' to never learn any key from the IMA keyring measurements",
256+
"items": {
257+
"type": "string",
258+
"title": "Keyring name"
259+
}
260+
},
261+
"log_hash_alg": {
262+
"type": "string",
263+
"title": "IMA entry running hash algorithm",
264+
"description": "The hash algorithm used for the running hash in IMA entries (second value). The kernel currently hardcodes it to sha1.",
265+
"const": "sha1"
266+
}
267+
},
268+
"required": ["ignored_keyrings", "log_hash_alg"],
269+
"additionalProperties": false
270+
}
271+
},
272+
"required": ["meta", "release", "digests", "excludes", "keyrings", "ima", "ima-buf", "verification-keys"],
273+
"additionalProperties": false
274+
}
275+
```
276+
### Verifier API changes
277+
The option `ima_sign_verification_keys` will be removed. `allowlist` will be
278+
renamed to `ima_policy` and only accepts a policy formatted in the schema above.
279+
280+
281+
### Database changes
282+
In `verifiermain` the column `ima_sign_verification_keys` will be dropped and
283+
the column `allowlist` will be renamed to `ima_policy`.
284+
285+
286+
### Tenant changes
287+
Following changes are made to the tenant.
288+
289+
#### New options
290+
* `--ima-policy`: Path to IMA policy in JSON format.
291+
* `--ima-policy-url`: URL to IMA policy in JSON format.
292+
* `--ima-policy-checksum`: SHA256 of the IMA policy.
293+
* `--ima-policy-sig`: Path to the signature of the IMA policy.
294+
* `--ima-policy-sig-url`: URL to the signature of the IMA policy.
295+
* `--ima-policy-sig-key`: Key to verify the signature against (in the tenant).
296+
297+
298+
#### Removal of following options
299+
* `--allowlist`: Renamed to `--ima-policy`. No longer accepts flat files.
300+
* `--allowlist-url`: Renamed to `--ima-policy-url`.
301+
* `--allowlist-checksum`: Renamed to `--ima-policy-checksum`.
302+
* `--allowlist-sig`: Renamed to `--ima-policy-sig`.
303+
* `--allowlist-sig-url`: Renamed to `--ima-policy-sig-url`.
304+
* `--allowlist-sig-key`: Renamed to `--ima-policy-sig-key`.
305+
* `--exclude`: Is now part of the IMA policy.
306+
* `--signature-verification-key`: The signature verification key is now part of
307+
the IMA policy.
308+
* `--signature-verification-key-sig`: A separate signature is no longer needed,
309+
because it is part of the IMA policy.
310+
* `--signature-verification-key-sig-key`: Same as above.
311+
* `--signature-verification-key-url`: Same as above.
312+
* `--signature-verification-key-sig-url`: Same as above.
313+
314+
The flat file to JSON conversion code will be moved out of the tenant into the
315+
conversion tool. If a no longer supported argument is specified the tenant
316+
errors with a note to use the conversion tool.
317+
318+
### Conversion tool
319+
The conversion tool takes the removed options, does the optional verification
320+
locally and returns a JSON policy. This will provided as a separate commandline
321+
tool called `keylime_convert_allowlist`.
322+
323+
324+
### IMA policy creation tool
325+
Keylime provides a `create_allowlist` script that tries to produce an allowlist
326+
from a running system. A new `create_ima_policy` script will be provided to do
327+
the same for the new format. Note that these scripts only create examples and
328+
not something that should be used in production.
329+
330+
### Test Plan
331+
332+
Existing tests for the IMA allowlist are migrated.
333+
334+
335+
### Upgrade / Downgrade Strategy
336+
337+
Old database entries are converted during the upgrade. For downgrading the
338+
agents have to be manually re-added with the different options.
339+
340+
### Dependency requirements
341+
342+
No new mandatory dependencies will be added. We might add a optional dependency
343+
for implementing JSON schema validation.
344+
345+
## Drawbacks
346+
347+
The JSON format is more complex that the old flat file format, but more flexible
348+
and future proof.
349+
350+
## Alternatives
351+
352+
* Keep the current configuration.
353+
* Use another policy format like TOML or YAML.
354+
355+
## Infrastructure Needed (optional)
356+
357+
<!--
358+
Use this section if you need things infrastructure related specific to your enhancement. Examples include a
359+
new subproject, repos requested, github webhook, changes to CI (travis).
360+
-->

0 commit comments

Comments
 (0)