Skip to content

Latest commit

 

History

History
360 lines (296 loc) · 13.7 KB

70_ima_policy.md

File metadata and controls

360 lines (296 loc) · 13.7 KB
Raw

enhancement-70: Merge allow and exclude list into an IMA policy

Release Signoff Checklist

  • 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]

Summary

This enhancement proposal changes and unifies the IMA configuration options by formally specifying a JSON schema. The tenant and verifier are modified to use the IMA policy instead of the old flat file format to simplify the process and allow further development like server side signature validation.

For users of the old flat file format a upgrade path using a commandline tool will be provided.

Motivation

The configuration for IMA validation is currently split over multiple options and is not well documented. This makes it confusing to use and hard to implement features like signature validation or storing all the information in a separate DB table to reuse.

Goals

  • Merge the current allow and exclude list into one single JSON object
  • Move ima_sign_verification_keys also into the JSON object
  • Deprecate flat file allow and exclude list
  • Simplify IMA related options in the tenant
  • Provide a tool for converting flat file allow and exclude list to JSON object
  • Convert the create_allowlist script to create a ima_policy.

Non-Goals

  • Change the current behavior of the IMA validation
  • Change how the measured boot reference state works
  • Implement server side signature validation

Proposal

The entries ima_sign_verification_keys and allowlist will be replaced with ima_policy in the verifier API. ima_policy takes a JSON object that contains all the required data for IMA validation. A schema for the JSON object will be provided in the Keylime repository.

The allowlist* options in the tenant will be renamed to ima_policy*.

The flat file format will be deprecated in favor of the JSON format. This is done to simplify future development like server side signature validation. For users of the old format a conversion tool will be provided.

User Stories

Story 1a - Using the legacy flat file format

  • User generates a allowlist ima_allowlist.txt and a exclude list exclude.txt
  • Conversion to new JSON format with keylime_convert_allowlist --allowlist ima_allowlist.txt --exclude exclude.txt --out ima_policy.json
  • The conversion tool produces ima_policy.json
  • Adds a new agent with keylime_tenant -c add --ima_policy ima.json ...
  • Agent is added to attestation.

Story 1b - Using the legacy flat file format with signature

  • User generates a allowlist ima_allowlist.txt and a exclude list exclude.txt, allowlist signature ima_allowlist.txt.sig and the public key allowlist.key
  • 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
  • The conversion tool validates the signature and produces ima_policy.json
  • Adds a new agent with keylime_tenant -c add --ima_policy ima.json ...
  • Agent is added to attestation.

Note that in this case the signature is checked by the conversion tool and that the exclude list does not have a signature that can be validated. This is fine because the signature validation is currently only done locally.

Story 2a - Using a JSON policy

  • User generates a IMA JSON policy called ima.json
  • Adds a new agent with keylime_tenant -c add --ima_policy ima.json ...
  • Agent is added to attestation.

Story 2b - Using a JSON policy with signature

  • User generates a IMA JSON policy called ima.json and has a signature ima.json.sig and a public key policy.key.
  • 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 ...
  • Agent is added to attestation.

Notes/Constraints/Caveats

  • This only affects the server side API of the verifier. Therefore we will not implement backwards compatibility for older tenant versions.
  • Signature validation in the tenant will be only possible with the JSON schema.

Risks and Mitigations

There are no new risks because we are just unifying the existing configuration options.

Design Details

New IMA policy JSON schema

The IMA policy is formally specified as:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Keylime IMA policy",
    "type": "object",
    "properties": {
        "meta": {
            "type": "object",
            "properties": {
                "version": {
                    "type": "integer",
                    "description": "Version number of the IMA policy schema"
                }
            },
            "required": ["version"],
            "additionalProperties": false
        },
        "release": {
            "type": "number",
            "title": "Release version",
            "description": "Version of the IMA policy (arbitrarily chosen by the user)"
        },
        "digests": {
            "type": "object",
            "title": "File paths and their digests",
            "patternProperties": {
                ".*": {
                    "type": "array",
                    "title": "Path of a valid file",
                    "items": {
                        "type": "string",
                        "title": "Hash of an valid file"
                    }
                }
            }
        },
        "excludes": {
            "type": "array",
            "title": "Excluded file paths",
            "items": {
                "type": "string",
                "format": "regex"
            }
        },
        "keyrings": {
            "type": "object",
            "patternProperties": {
                ".*": {
                    "type": "string",
                    "title": "Hash of the content in the keyring"
                }
            }
        },
        "ima-buf": {
            "type": "object",
            "title": "Validation of ima-buf entries",
            "patternProperties": {
                ".*": {
                    "type": "string",
                    "title": "Hash of the ima-buf entry"
                }
            }
        },
        "verification-keys": {
            "type": "array",
            "title": "Public keys to verify IMA attached signatures",
            "items": {
                "type": "string"
            }
        },
        "ima": {
            "type": "object",
            "title": "IMA validation configuration",
            "properties": {
                "ignored_keyrings": {
                    "type": "array",
                    "title": "Ignored keyrings for key learning",
                    "description": "The IMA validation can learn the used keyrings embedded in the kernel. Use '*' to never learn any key from the IMA keyring measurements",
                    "items": {
                        "type": "string",
                        "title": "Keyring name"
                    }
                },
                "log_hash_alg": {
                    "type": "string",
                    "title": "IMA entry running hash algorithm",
                    "description": "The hash algorithm used for the running hash in IMA entries (second value). The kernel currently hardcodes it to sha1.",
                    "const": "sha1"
                }
            },
            "required": ["ignored_keyrings", "log_hash_alg"],
            "additionalProperties": false
        }
    },
    "required": ["meta", "release", "digests", "excludes", "keyrings", "ima", "ima-buf", "verification-keys"],
    "additionalProperties": false
}

Verifier API changes

The option ima_sign_verification_keys will be removed. allowlist will be renamed to ima_policy and only accepts a policy formatted in the schema above.

Database changes

In verifiermain the column ima_sign_verification_keys will be dropped and the column allowlist will be renamed to ima_policy.

Tenant changes

Following changes are made to the tenant.

New options

  • --ima-policy: Path to IMA policy in JSON format.
  • --ima-policy-url: URL to IMA policy in JSON format.
  • --ima-policy-checksum: SHA256 of the IMA policy.
  • --ima-policy-sig: Path to the signature of the IMA policy.
  • --ima-policy-sig-url: URL to the signature of the IMA policy.
  • --ima-policy-sig-key: Key to verify the signature against (in the tenant).

Removal of following options

  • --allowlist: Renamed to --ima-policy. No longer accepts flat files.
  • --allowlist-url: Renamed to --ima-policy-url.
  • --allowlist-checksum: Renamed to --ima-policy-checksum.
  • --allowlist-sig: Renamed to --ima-policy-sig.
  • --allowlist-sig-url: Renamed to --ima-policy-sig-url.
  • --allowlist-sig-key: Renamed to --ima-policy-sig-key.
  • --exclude: Is now part of the IMA policy.
  • --signature-verification-key: The signature verification key is now part of the IMA policy.
  • --signature-verification-key-sig: A separate signature is no longer needed, because it is part of the IMA policy.
  • --signature-verification-key-sig-key: Same as above.
  • --signature-verification-key-url: Same as above.
  • --signature-verification-key-sig-url: Same as above.

The flat file to JSON conversion code will be moved out of the tenant into the conversion tool. If a no longer supported argument is specified the tenant errors with a note to use the conversion tool.

Conversion tool

The conversion tool takes the removed options, does the optional verification locally and returns a JSON policy. This will provided as a separate commandline tool called keylime_convert_allowlist.

IMA policy creation tool

Keylime provides a create_allowlist script that tries to produce an allowlist from a running system. A new create_ima_policy script will be provided to do the same for the new format. Note that these scripts only create examples and not something that should be used in production.

Test Plan

Existing tests for the IMA allowlist are migrated.

Upgrade / Downgrade Strategy

Old database entries are converted during the upgrade. For downgrading the agents have to be manually re-added with the different options.

Dependency requirements

No new mandatory dependencies will be added. We might add a optional dependency for implementing JSON schema validation.

Drawbacks

The JSON format is more complex that the old flat file format, but more flexible and future proof.

Alternatives

  • Keep the current configuration.
  • Use another policy format like TOML or YAML.

Infrastructure Needed (optional)