adds ssh host key validation usage doc

content/boundary/v0.21.x/content/docs/workers/ssh-host-key.mdx

@@ -0,0 +1,109 @@
+---
+layout: docs
+page_title: Verify SSH host identity
+description: >-
+  Learn about configuring SSH host key validation to ensure workers connect to the correct servers and to reduce the risk of man-in-the-middle attacks.
+---
+
+# 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](/boundary/docs/workers/multi-hop).
+
+## 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](/boundary/docs/workers/create). 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:
+
+<CodeBlockConfig filename="/etc/ssh/ssh_known_hosts">
+
+```bash
+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=
+```
+
+</CodeBlockConfig>
+
+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](/boundary/docs/configuration/workers) in the worker config file. In this example, the worker has a `public_addr` set, but this is not required.
+
+<CodeBlockConfig lineNumbers filename="/etc/boundary.d/egress-worker.hcl">
+
+```hcl
+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"]
+  }
+}
+```
+
+</CodeBlockConfig>
+
+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`.
+1. 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:
+
+```shell-session
+$ sudo systemctl restart boundary-worker
+```
+
+To SIGHUP the worker instead, locate the PID of the worker service. For example:
+
+```shell-session
+$ pgrep boundary-worker
+59431
+```
+
+Then reload the configuration file for the process using `SIGHUP`:
+
+```shell-session
+$ 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:
+
+<CodeBlockConfig filename="/etc/ssh/ssh_known_hosts">
+
+```bash
+cert-authority * ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH7GQfxksmG7lzS0222Tu4SHNYW3iA3E8bdrUQTqaQUu
+```
+
+</CodeBlockConfig>
+
+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](/boundary/docs/workers/multi-hop) 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.

content/boundary/v0.21.x/data/docs-nav-data.json

@@ -450,6 +450,10 @@
         "title": "Route traffic through a worker",
         "path": "workers/worker-tags"
       },
+      {
+        "title": "Configure SSH host key validation",
+        "path": "workers/ssh-host-key"
+      },
       {
         "title": "Configure a worker filter",
         "path": "workers/filters"