Skip to content

Latest commit

 

History

History
197 lines (150 loc) · 8.19 KB

114-agent-multiple-api.md

File metadata and controls

197 lines (150 loc) · 8.19 KB

enhancement-114: Add support for multiple API versions to the agent

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

Add support for multiple API versions in the agent, making it possible for it to communicate with older versions of the verifier, registrar, and tenant.

Motivation

Currently, the agent only supports the latest API version, meaning that it will not accept connections from older versions of the other Keylime components nor make requests using an older API version to communicate with them. This means that deployments based on older versions of the Keylime server components cannot monitor machines running agents that have a newer API version.

Specifically for long-term supported distributions, such as RHEL, the lack of the ability to monitor systems that have a newer version of the agent with infrastructure based on older server components means that the agent cannot be updated without breaking compatibility. This is not acceptable for long-term supported distributions, resulting in the agent being held in an older version for a long period to keep compatibility, making maintenance difficult as the time passes, since the gap between the latest upstream version and the supported version could grow too big.

The other components already support communicating with older versions of the agent; adding this support to the agent would make it possible to have deployments with components on mixed versions.

Goals

Make the agent backwards compatible, allowing a system running a newer version of the agent to be monitored by attestation infrastructure based on an older versions of the server components.

Non-Goals

Support all existing API versions is a non-goal: only a number of the latest versions should be supported, given they are compatible.

Proposal

The proposal is to make the agent capable of communicating with older versions of the other components. For this, it is required that the agent support receiving connections using older API versions, as well as making it possible for the agent to use older API versions when making requests to the other components.

To make it possible for the agent to receive connections from older versions of the other components, the agent should provide endpoints under multiple API versions instead of using only the latest API version.

On the other way around, for the agent to be able to connect to a server that supports only older versions of the API, the agent should use a compatible API version when making requests (e.g. when registering itself with the registrar).

To make the agent capable of choosing a compatible API version when making requests, the other components should implement an endpoint similar to the /version endpoint provided by the agent. This endpoint should provide the latest supported API version, making it easy for the agent to query for the supported API version and adjust its requests accordingly.

In the absence of this new endpoint, the agent can try to reach the other components by trial and error using supported older versions. Although this is not an efficient method, it is the only way for the agent to communicate with older versions of the other components without having a way to query the supported version.

If possible, the user should be able to select a subset of the supported API versions to enable via configuration options. To keep the current behavior (only accept the latest API version), the configuration option could support a special keyword (e.g. "latest") to only support the latest API version.

User Stories (optional)

Story 1

As a system administrator with an existing Keylime deployment in production, I want to add new machines to be monitored, but using a newer version of the Keylime agent on those machines. The newer version of the Keylime agent running on those machines should be able to communicate with my existing deployed Keylime components (verifier, registrar, and tenant).

Story 2

As a system administrator with an existing Keylime deployment in production, I want to update the version of the Keylime agent used in my monitored machines. The updated version of the Keylime agent should be able to communicate with my existing deployed Keylime components (verified, registrar, and tenant).

Notes/Constraints/Caveats (optional)

No caveats were identified at the moment.

Risks and Mitigations

No risks were identified at the moment.

Design Details

The proposed changes to the server components other than the agent are:

  • Provide the /version endpoint which replies to GET requests with the latest supported API version. The provided endpoint response format should follow the current response provided by the agent /version endpoint:
{
  "code": 200,
  "status": "Success",
  "results": {
    "supported_version": "2.0"
  }
}

The proposed changes to the agent are:

  • The agent provides the endpoints to receive connections under multiple API versions (e.g. /v2.1/quotes/identity and /v2.0/quotes/identity)
    • Ideally the user can configure a subset of the supported API versions to enable via configuration. The agent should provide the endpoints under the selected API versions.
      • For example: from the set of supported versions ['2.0', '2.1', '2.2], the user could select which versions to enable by setting the configuration option api_versions = ['2.1', '2.2']
  • When connecting to a remote server, the agent makes requests using an API version supported by the remote server it is contacting.
    • If the remote server provides the /version endpoint, the agent should first query this endpoint with a GET request to obtain the latest supported version. Then the agent should adjust all the requests it creates to use the supported version
    • In the absence of the /version endpoint on the remote server (which will be the case for the current existing server components), the agent should try older supported API versions, starting with the newest to contact the remote server. Once the connection is established, the agent should store the used API version and reuse in future connections.

Test Plan

Unit tests should be added to the repository test suite. Functional and end-to-end tests should be added to the tests repository (https://github.com/RedHat-SP-Security/keylime-tests) and added to the CI.

The tests should include mixing agents running older API versions with other components running newer API versions and vice-versa.

Upgrade / Downgrade Strategy

When upgrading, the agent should be configured with a sane default value. The suggested is to be configured with all the latest compatible API versions.

Dependencie requirements

No new dependencies should be required

Drawbacks

No drawbacks were identified at the moment

Alternatives

Not implementing this enhancement. In this case, the agent will continue to be incompatible with components using older API versions.

Users would not be able to monitor agents running with newer API versions with other components on older API versions. They can still monitor agent running on older API versions with other components that have a newer API version.

Infrastructure Needed (optional)

No special infrastructure is needed.