Rotating Host Keys

This section describes how you can rotate host keys.

note

Host key rotation is supported only for Tectia and OpenSSH servers. For more information about the supported operating systems, see the Key Manager Product Description.

Ensure that target hosts' SSH configurations are in the managed state. You can check the SSH configurations and their states via the Hosts→SSH Configurations page in the Key Manager GUI.

note
SSH configurations are automatically put to the managed state when their hosts are switched to the managed state.
Generate new host keys using the generate-host-keys command, selecting target host(s) using -i or -F option. We recommend you tag the generated host keys with a tag unique to this specific operation, so that you can more easily target the new keys in the following steps.

Example: Generating host keys for one host
```
$ ssh-mgr-client generate-host-keys -i 55 \
-d product_tag=ssh-g3-server,key_alg=rsa,key_size=2048,tags=new_hostkey_5
```
Example: Generating host keys for multiple hosts
```
$ ssh-mgr-client generate-host-keys -F 'hostgroup="Example Hosts"' \
-d product_tag=ssh-g3-server,key_alg=rsa,key_size=2048,tags=new_hostkey_5
```
note
The generate-host-keys command generates keys based on one key algorithm at a time. To renew all host keys, generate each desired new key, and tag them all with the same tag to target all the keys at the same time in the following steps.
The supported values for product_tag are the same as those available for the setting Preference order of server products for new keys (preferred_server_products). You can find the setting from the Settings→General→Host page.
Configure SSH clients to trust the new host keys:

i. Perform key-activity scans on all target and client hosts. Key Manager uses the key-activity data to determine which clients need updating.

ii. Update the newly generated host keys to all relevant managed-client hosts:
```
$ ssh-mgr-client update-known-hosts -d host_key_tags=new_hostkey_5
```
Key Manager will update all clients that have key activity to target hosts.

note
The update-known-hosts command adds the newly-generated keys to the SSH clients' global known_hosts file. By default, SSH clients on Unix hosts record servers' host keys in a user-specific known_hosts file located in ~/.ssh/ directory.
When rotating a host key, Key Manager will not remove the old host key from the user-specific known_hosts files.
Key Manager cannot automatically update trusts for OpenSSH clients older than version 5.7. To prevent connections terminating due to host key changed errors, either upgrade the OpenSSH client prior to host-key renewal, or remove the old host key entries from the user-specific known_hosts files.
note
On Windows hosts using Tectia client, the known hosts file is named ssh-known-hosts and is located in the Tectia Broker directory in C:\Program Files (x86)\SSH Communications Security\SSH Tectia\SSH Tectia Broker. This file needs to be added to the Tectia Broker configuration files.
You can either add the file to the global configuration file, or ask users to add the file to their own configuration files to allow them to further add their own configurations as needed.
Example of adding the known hosts file to the Tectia configuration files:
<general> ... <known-hosts path="C:\ProgramData\SSH\hostkeys\known_hosts"/> <known-hosts path="%APPDATA%\SSH\hostkeys"/> </general>
note
The known hosts entries generated by the Key Manager assume that each SSH server uses the default port. In cases where the SSH servers running a non-standard port, you must manually add the port to the server identities in the known hosts file.

Rotate the previously-generated keys into use:

$ ssh-mgr-client rotate-host-keys -F tags=new_hostkey_5

Update the known hosts files again to remove the keys that were rotated out:
```
$ ssh-mgr-client update-known-hosts -d host_key_tags=new_hostkey_5
```