Skip to content

Latest commit

 

History

History
182 lines (149 loc) · 7.35 KB

47_agent_ip_port.md

File metadata and controls

182 lines (149 loc) · 7.35 KB
Raw

enhancement-47: Let the agent provide contact IP and port for verifier

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

The agents gains the ability to provide the registrar with a contact ip and port for the verifier.

Motivation

The verifier needs a port and ip adress to contact a agent. Currently this information is manually provided to the tenant.

This information can also be provided by the agent in most cases. It makes Keylime more user friendly in environments where no external configuration management is used.

Allowing configuration with environment variables allows other tools to set this information easily before the agent is started.

Goals

  • Add support for the agent to specify a contact ip and port
  • Static configuration in config file or specified via environment variable
  • Extending registrar API to allow specifying contact ip and port
  • Add support for using the specified ip and port to the tenant

Non-Goals

  • Moving Keylime to model to a push only model
  • Allow IP changes after registration
  • Auto detection of IP and port

Proposal

This enhancement proposal adds that the agent can provide a contact IP and port for the verifier to the registrar. The tenant does not have to ask the user manually for this data anymore and tries to retrieve it from the registrar.

User Stories

Story 1

  • Agent has contact ip and port configured
  • Agent registers itself with the registrar
  • User adds agent with keylime_tenant -c add -u AGENT_ID
  • Tenant retrieves the ip and port information from the registrar
  • Agent is added to the verifier

Story 2

  • Agent has contact ip and port not configured
  • Agent registers itself with the registrar
  • User adds agent with keylime_tenant -c add -t 127.0.0.1 -u AGENT_ID (127.0.0.1 is the IP of the agent)
  • Agent is added to the verifier

Story 3

  • Agent has contact ip and port not configured
  • Agent registers itself with the registrar
  • User adds agent with keylime_tenant -c add -u AGENT_ID
  • Tenant fails because the IP cannot be retrieved from the registrar

Risks and Mitigations

The input by the agent is generally not trusted and must be validated. Is is done in the registrar.

Design Details

To the registrar database table registrarmain two new columns are added: ip and port. Those entries can be NULL.

The fields ip and port can be optionally specified in the registrar API when a agents tries to register. Simple input validation for those fields is added in the registrar.

The agent configuration gains two new optional fields agent_contact_ip and agent_contact_port. Those options can also be specified as environment variables with KEYLIME_AGENT_CONTACT_IP and KEYLIME_AGENT_CONTACT_PORT. Environment variables have a higher precedence.

The --targethost option for the tenant is made optional and if not specified the tenant tries to retrieve the data from the registrar automatically. The same goes for the port. The tenant can assume that this data is validated. The precedence is first command line argument, values from the registrar and then default value from config (last one only applies to port).

Test Plan

  • Extending the test_registrar_db.py test to test the new fields
  • Extending the test_restful.py tests to check for the registration with an IP and port and without.

Upgrade / Downgrade Strategy

To the registrarmain table two new columns are added ip and port. Those fields can be NULL. The registrar API gains two new fields ip and port but those can be empty such that old agents still can connect.

A minor update to the API should be done to indicate that the registrar supports the new fields.

A downgrade of the agents should possible without any changes. If the registrar is downgraded the columns can be removed and the tenant now needs to specify those fields explicitly again.

Dependency requirements

No additional dependencies should be required.

Drawbacks

  • Additional data is stored which in some cases could also be retrieved from tools outside of Keylime.

Alternatives

  • In some enhancements the contact IP and port can also be retrieved via third party configuration tools.
  • Moving Keylime to a model where the agent polls the registrar and pushes the data to the verifier periodically. This would eliminate the need for the verifier or tenant to contact the agent directly but requires heavy changes to Keylime.