Skip to content

Latest commit

 

History

History
316 lines (248 loc) · 12.3 KB

53_agent_local_revocation.md

File metadata and controls

316 lines (248 loc) · 12.3 KB
Raw

enhancement-53: Agent-local Revocation Notification Mechanism

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

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.

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.