diff --git a/53_agent_local_revocation.md b/53_agent_local_revocation.md new file mode 100644 index 0000000..7deefac --- /dev/null +++ b/53_agent_local_revocation.md @@ -0,0 +1,316 @@ + +# enhancement-53: Agent-local Revocation Notification Mechanism + + + + + + +- [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 + + + +- [x] 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 + + + +Keylime agent currently receives revocation notifications through +ZeroMQ over TCP. The agent connects to the revocation notifier +service, typically run by the verifier, and waits for any revocation +being sent. + +While this setup works well in practice, it is not ideal in certain +deployment scenarios such as IoT. This enhancement provides an +alternative revocation notification mechanism and the configuration +options. + +## Motivation + + + +### Dependencies of ZeroMQ implementations + +The reference implemention of ZeroMQ ([libzmq]) has quite a few +run-time dependencies including libsodium (for cryptography) and +openpgm (for multicast), which are not always available in restricted +environment. + +While revocation notification can be turned off at run-time, this is +particularly problematic for Rust agent, because whether the ZeroMQ +feature is supported needs to be determined at build time. Although +there is a pure-Rust rewrite of ZeroMQ ([zmq.rs]) which can be +configured without such dependencies, it depends on a newer async +runtime (tokio 1.x) incompatible with the one used by the Rust agent. + +### Goals + + + * Add support for the agent to listen on revocation notification without ZeroMQ transport + * Add support for the verifier to send out revocation notification without ZeroMQ transport + +### Non-Goals + + + * Secure execution of revocation actions by the agent (while it is desired) + * Moving Keylime to a push-only model + +## Proposal + + + +This enhancement proposal adds a new revocation notification mechanism +natively integrated into the agent protocol, as well as the supporting +configuration options to allow the verifier to use multiple revocation +notification mechanisms together. + +### User Stories (optional) + + + +#### Story 1 + * Verifier has `revocation_notifiers` with the value "agent" configured + * Agent registers itself with the registrar + * User adds agent with `keylime_tenant -c add -u AGENT_ID` + * Agent is added to the verifier + * Verifier sends revocation notification to the agent through the REST API + * Agent executes revocation actions + +### Notes/Constraints/Caveats (optional) + + + * The API version needs to be bumped to a new minor version, as this change falls under the "Adding a new API endpoint would be a minor version bump as previous clients would not be using it" [criteria](https://github.com/keylime/enhancements/blob/master/45_api_versioning.md#design-details). + +### Risks and Mitigations + + + +The attack surface on the agent protocol slightly increases as the new +REST resource (`/v1.0/notifications/revocation`) is added, though the +messages are digitally signed and cannot be exploited as long as the +agent is properly implemented/configured. + +## Design Details + + + +The REST API of the agent will export a new resource at +`/v1.0/notifications/revocation`, which can be accessed with a POST +method. The request body is a JSON object with the following properties: + +- `msg` (_string_) - argument passed to the revocation actions +- `signature` (_string_) - signature calculated over `msg`, using RSA-PSS with SHA-256 as the hash algorithm and the maximum salt length for the RSA key, in base64 format + +At the agent side, the method and the invocation of the revocation +actions should be implemented as idempotent, so that it should not +matter how many times the method is called. + +In the `cloud_verifier` section of the configuration file, a new +option `revocation_notifiers` is added to select notification +mechanisms that the verifier uses. The option takes a list of strings +and the possible values are `zeromq`, `webhook`, and `agent`. + +The former two have the same effect as the current +`revocation_notifier` and `revocation_notifier_webhook`, while the +latter (`agent`) enables push notification to the agent, based on the +REST API described above. + +The `revocation_notifier` and `revocation_notifier_webhook` options +are deprecated and mutually exclusive with `revocation_notifiers`. The +new code supporting this enhancement should put a warning in the log +that the options are deprecated and suggest the required changes. + +### Test Plan + + + + * Extend the `test_restful.py` tests to check for the new protocol. + +### Upgrade / Downgrade Strategy + + +To upgrade/downgrade, the configuration file needs modification if it +makes use of the new configuration option (`revocation_notifiers`). A +helper script could be provided to ease the migration + +### Dependencie requirements + + +No additional dependencies should be required. + +## Drawbacks + + +No drawbacks are known of. + +## Alternatives + + + * It is possible to use other asynchronous messaging technology or + design custom protocol without imposing dependencies. However, the + agent is already listening on a REST endpoint, reusing the agent + protocol would be straightforward. + +## Infrastructure Needed (optional) + + +No infrastructure changes needed. + +[libzmq]: https://github.com/zeromq/libzmq/ +[zmq.rs]: https://github.com/zeromq/zmq.rs/