ssh_known_hosts file format

The /etc/ssh/ssh_known hosts and ~/.ssh/known_hosts files contain the host public keys for all known hosts. The use of the global file is optional; if it is used, it must be prepared by the administrator. The per-user file is maintained automatically. Each time the user connects from an unknown host, the key of that unknown host is added to the per-user file

Each line in these files contains the following fields, and the fields are separated by spaces:

For RSA, DSA, ECDSA, or Ed25519 from the id_rsa.pub, id_dsa.pub, id_ecdsa.pub, or id_ed25519.pub files:

marker (optional), hostnames, key-type, public-key, comment End of change

For RSA or DSA from the key ring:

hostnames, zos-key-ring-label="KeyRingOwner/KeyRingName label"

zos-key-ring-label specifies the key ring owner, key ring name of the name of the known_hosts SAF key ring, and the certificate label of the certificate within the key ring on the OpenSSH client that contains the host public key. One or more blanks separate the key ring (real or virtual) name from the certificate label. Certificate labels can contain embedded blanks. The option value must be enclosed in double quotes. Any fields following zos-key-ring-label on the same line are ignored. The zos-key-ring-label specification keyword is not case sensitive.

Requirement: The certificate must be copied from the server system and added to the known hosts file or key ring on the OpenSSH client.

If a key ring is being used on the client side, for example, SSHKnownHostRing, the key ring was created in the server authentication setup as described in Steps for setting up server authentication when keys are stored in key rings.

The marker is optional, but if it is present then it must be one of "@cert-authority", to indicate that the line contains a certification authority (CA) key, or "@revoked", to indicate that the key contained on the line is revoked and must not ever be accepted. Only one marker should be used on a key line. See Certificates for more information on SSH-style certificates.

Hostnames is a comma-separated list of patterns (* and ? act as wildcards). Each pattern is matched against the canonical host name when authenticating a client or against the user-supplied name when authenticating a server. A pattern can also be preceded by ! to indicate negation. If the host name matches a negated pattern, it is not accepted by that line even if it matched another pattern on the line. A hostname or address can optionally be enclosed within '[' and ']' brackets, then followed by ':' and a nonstandard port number.

Alternatively, hostnames can be stored in a hashed form which hides host names and addresses if the file's contents are disclosed. Hashed hostnames start with a '|' character. Only one hashed hostname can appear on a single line and none of the above negation or wildcard operators can be applied.

Start of change The keytype and base64-encoded key are taken directly from the host key; they can be obtained, for example, from /etc/ssh/ssh_host_rsa_key.pub. The optional comment field continues to the end of the line, and is not used. End of change

Lines starting with # and empty lines are ignored as comments.

When performing host authentication, authentication is accepted if any matching line has the proper key, either one that matches exactly or, if the server has presented a certificate for authentication, the key of the certification authority that signed the certificate. For a key to be trusted as a certification authority, it must use the ``@cert-authority'' marker described previously.

The known hosts file also provides a facility to mark keys as revoked, for example when it is known that the associated private key has been stolen. Revoked keys are specified by including the ``@revoked'' marker at the beginning of the key line, and are never accepted for authentication or as certification authorities, but instead will produce a warning from ssh when they are encountered.

It is thus permissible (but not recommended) to have several lines or different host keys for the same names. This will happen when short forms of host names from different domains are put in the file. It is possible that the files contain conflicting information. Authentication is accepted if valid information can be found from either file.

The lines in these files are typically hundreds of characters long and should be generated by a script, ssh-keyscan, or by taking /etc/ssh/ssh_host_key.pub and adding the host names at the front. ssh-keygen(1) also offers some basic automated editing for ~/.ssh/known_hosts, including removing hosts matching a host name and converting all host names to their hashed representations.

An example of a ssh_known_hosts file:

# Comments allowed at start of line
closenet,...,192.0.2.53 1024 37 159...93 closenet.example.net
cvs.example.net,192.0.2.10 ssh-rsa AAAA1234.....=
# A hashed hostname
|1|JfKTdBh7.....= ssh-rsa AAAA1234.....=
# An example specification of a known host key from a key ring
mvs* zos-key-ring-label="KeyRingOwner/SSHKnownHostsRing mvs1-ssh-rsa"