diff --git a/signature_body.md b/signature_body.md new file mode 100644 index 0000000..8f81533 --- /dev/null +++ b/signature_body.md @@ -0,0 +1,327 @@ + +# 77-signature_body: Attached signatures + +Utilise signature body in allow list for attached signatures. + + + + + + +- [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) + + +## 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 `in-progress` +- [ ] Design details are appropriately documented +- [ ] Test plan is in place +- [ ] User-facing documentation has been created in [keylime/keylime-docs] + + + +## Summary + +This proposal introduces a method to sign over the body of an allow-list +and then attach a signature and public key ID or X509 certificate. + +It uses the same manifest layout as supply chain projects [intoto](https://in-toto.io/) +and [The update framework](https://theupdateframework.io/). + + +## Motivation + +The current implementation leverages seperate keys to the list itself. While +suitable for some cases, it is also useful to have a single package where the +list and the signature travel in the same payload. + + + +### Proposal + +User produces a cryptographic signature by 'passing over' the body of an allow/exclude +list. The signature and public key id (sha256 hash of pubKey), or an X509 cert (base64) +are then attached to the allowlist. + +The verifier upon discovery of a `"signed"` body and `"signatures"` keys, will validate +the `signed` section. + +This proposal borrows from the existing signing conventions +established by the [intoto project](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#4-document-formats). + +```json +{ + "signatures": [ + { + "keyid": , + "keytype" : , + "sig": + } + ], + "signed": { + "meta": { + "version": 872 + }, + "release": 774.75, + "hashes": { + ",'Sr": [] + }, + "excludes": [], + "keyrings": { + "}": "xxx" + }, + "ima": { + "ignored_keyrings": [], + "log_hash_alg": "xxx" + }, + "ima-buf": { + "": "xxx" + }, + "verification-keys": [] + } +} +``` +#### signatures + +The `signatures`` section lists there json keys: + +##### keyid + +* keyid: The keyid can be one of two. +1. A sha256 hash of a public key (therefore acting as a map). This allows an out-of-band public key +2. A base64 encoded X509 v3 certificate in PEM format. This is in-band and can be chained to CA for identity. + +For the first method (sha256 hash) the public key will be stored within the verifier at: + +`/var/lib/keylime/signing_keys/{hash-of-pubkey}.pkey` + +For the second method a store is not required, the public key can be extracted from the X509 certificate + +For a later stage, we can look to have a chain verification from the the signing cert to a CA. + +##### keytype + +keytype is a string denoting a public key signature system. + +We define three key types at present: "rsa", "ed25519", and "ecdsa". + +##### sig + +The `sig` section is a base64 encoded signature (see signed below for details around signature generation) + +#### signed + +The signed body contains all content that is to be signed. + +The signature functionality, extracts all characters (including whitespace) and encodes it to a base64 string + +A signature is then generated by signing the base64 string. This is then placed into `sig` section within the +`signatures` body. + +### verification + +The verification flow, will play out as follows + +1. The verifier will check to see if the signature and signed bodies exist +2. The verifier will either decode the x509 certificate and extract the public key, or will capture + the sha256 digest and load the mapped key from `/var/lib/keylime/signing_keys/{hash-of-pubkey}.pkey` +3. The verifier will then perform a verification of the signature against the `signed` body +4. If any of the steps above fail, then a verifier API will return a failure code. + +### Non-Goals + + +No immediate plan to implement signing into the tenant and no extra flags are required, +the verifier will check for the signature and signed body and only attempt to validate +if they exist. + +### User Stories (optional) + + + +I as a user would like to have attached signatures. + +#### Story 1 + +#### Story 2 + +### Notes/Constraints/Caveats (optional) + + + +### Risks and Mitigations + + + +## Design Details + + + +### Test Plan + + + +Unit test will be provided to verify serialization of json input and +signature verification. + +### Upgrade / Downgrade Strategy + + + +### Dependency requirements + + + +No new dependencies will be required. + +## Drawbacks + + + +## Alternatives + + + +## Infrastructure Needed (optional) + +