Verify SSH host identity

This page describes how to configure SSH host key validation on workers to verify host identity when you connect to targets.

Operators may require Boundary workloads to be exposed to untrusted networks, including the public internet. These workloads may also be subject to strict security and compliance requirements. In these environments, SSH host key validation is a foundational control to ensure that clients are connecting to the intended servers and to reduce the risk of man-in-the-middle attacks.

SSH host key validation configures a worker to verify SSH host keys or host identity when establishing SSH sessions to targets.

This page shows an example for an egress worker, which is a worker that connects to targets. You can also set up host key validation for ingress and intermediate workers in multi-hop session deployments.

Configure host key validation

By default, Boundary workers do not perform any host key validation. When you start a session to a target, Boundary connects to that target.

To configure host key validation, add the ssh_known_hosts_path parameter to your worker config file. The path should point to a known hosts config file, such as the /etc/ssh/ssh_known_hosts on Linux or %ProgramData%\ssh\ssh_known_hosts on Windows. It does not matter whether you choose a known hosts file used by SSH, or a file you create that is only used by the worker.

A simple example of a known hosts file could look like the following:

34.60.29.233 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJL40LjsJlrXZAQvrt1mZFXpuRuA7hFjDjrZDjaOeUSB
34.60.29.233 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCe6pQi3znAs8j9p+z2LrO4+/gbG0UCiterVjyy4ya8XPQRNe7c2GJfIE5wspNgCY6iQbPV7h+t8aGgvkUuX+JD43glvabB5JTSEO1wjnmw628KA/9gAWuBqpaIF3i+l8V9N8enyw3R71mUF9FX8FAVc+qcO1E+2W3uvZZPFjwzJF5higYRyFmwxWxeJ8ZaWHIm/VQk/QFNBVDJN/3OGqSgjGt0NFfox3RpGM0MwUJViphnW7lAYKrSP0rc8SiKIWOi36JiOYCLFqRDv5QrevzPUhJj+KLls03ou/zP61Tv5xXXNniZZHmOuXVrWInnwMa9Qf/5kRAq2xuTimIYDR0lzdCEvZiw9UFYqQEGmyHsQouMU84j+ghh4+Rm36tIH8amKhmrxprZScwrbv6QxEjb66IOF2yATVinJ4oLgdVLRLqE3WAwzjUm4mIMe9C3tGemGjkhAv5ZZYhjgcw8TqBLEacYEVNa5aE+c9tq5sNB5fb2+ccdsEHV48Y3+MKllIk=

To enable SSH host key validation, you must reference the location of the known hosts file using the ssh_known_hosts_path parameter in the Boundary config file.

Below is an example for a generic worker stanza in the worker config file. In this example, the worker has a public_addr set, but this is not required.

worker {
  name = "web-prod-ssh-worker"
  public_addr = "10.0.0.10"

  ssh_known_hosts_path = "/etc/ssh/ssh_known_hosts"

  tags {
    region = ["us-east-1"]
    type   = ["prod", "webservers"]
  }
}

Add the ssh_known_hosts_file location to your worker config and save this file.

Enable host key validation

When the known hosts configuration changes, you must restart the worker service or SIGHUP the worker.

You can change the known hosts configuration in two places:

1. The worker config file, such as /etc/boundary.d/egress-worker.hcl.
2. The known hosts file, such as /etc/ssh/ssh_known_hosts.

If the content of either of these files changes, you must adopt these changes.

For example, if the worker service is named boundary-worker, you can restart the worker service:

$ sudo systemctl restart boundary-worker

To SIGHUP the worker instead, locate the PID of the worker service. For example:

$ pgrep boundary-worker
59431

Then reload the configuration file for the process using SIGHUP:

$ kill -SIGHUP 59431

Configure a certificate authority

You can configure a certificate authority (CA) to manage SSH key validation.

To use a CA for certificate validation, you can use wildcards to refer to your targets in your known hosts file, like the following:

cert-authority * ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH7GQfxksmG7lzS0222Tu4SHNYW3iA3E8bdrUQTqaQUu

This way, you can defer to a CA to manage host certificates for targets on your behalf instead of managing the known hosts file manually.

In this example, all targets are trusted by the CA using the pattern *. But you can use a more restrictive pattern, such as *.example.com. You can also add separate CAs to the known hosts file for different sets of targets.

Next steps

You can configure multi-hop sessions to chain workers together through a reverse proxy. Each worker in the multi-hop deployment can use SSH host key validation to enhance security when connecting to upstream workers.