ssh-keygen -r hostname prints the SSHFP DNS resource record for the host key on the local machine. The flag is for the rare case where you want to publish a host’s public key in DNS so a connecting client can verify the key against DNSSEC instead of against the local known_hosts file. The team that uses it is the team that has DNSSEC working and wants SSH trust to inherit the same chain.
Table of contents
- What SSHFP actually does
- When to use it (and when not to)
- The right command sequence
- Pitfalls to avoid
- Verifying the trust chain on the client
- FAQ
What SSHFP actually does
SSHFP (SSH Fingerprint) is a DNS resource record type that stores a host’s public key fingerprint. The format is: algorithm number, fingerprint type, fingerprint. A typical record looks like:
host.example.com. IN SSHFP 2 1 123456789abcdef67890123456789abcdef67890The 2 is the algorithm (2 = DSA, 1 = RSA, 3 = ECDSA, 4 = Ed25519). The 1 is the fingerprint type (1 = SHA-1, 2 = SHA-256). The hex is the fingerprint itself. When ssh-keygen -r hostname runs, it prints one of these lines for each host key on the local machine, ready to paste into a zone file.
The connection flow with SSHFP works like this. The client connects to the host. The host presents its public key. The client queries DNS for an SSHFP record at the host’s name. If the record exists and the DNSSEC chain validates, the client compares the host’s public key against the SSHFP record. If they match, the connection proceeds. If they do not match, the client rejects the connection. The known_hosts file is bypassed entirely for that first connection. Subsequent connections fall back to the standard known_hosts flow.
The advantage is that the trust chain for the host key is the same as the trust chain for the DNS name. With DNSSEC, the client does not need a separate out-of-band channel to learn the host’s key. The disadvantage is the entire DNSSEC chain has to be working. If DNSSEC validation fails, the SSH client will reject the SSHFP record and fall back to the standard known_hosts flow, which is the right behavior.
When to use it (and when not to)
The right use case is a managed fleet where DNSSEC is working, the SSH host keys change rarely, and you want the team to be able to SSH to new hosts without manually accepting a key fingerprint. The wrong use case is anything where DNSSEC is broken, where the team controls host keys through configuration management and not DNS, or where the host key changes more often than the DNS TTL.
The other thing to consider is that the SSHFP record is for the server host key, not for the client key that the user uses to authenticate. The client key is still in authorized_keys on the server, exactly as it has always been. SSHFP is purely about the trust-on-first-use problem for the server’s identity.
If you operate a small fleet and your team is comfortable accepting the host key fingerprint the first time they connect, SSHFP is not necessary. If you operate a large fleet and you have had a real-world incident where someone SSH’d to the wrong host because of a typo or a DNS hijack, SSHFP is the right answer.
The right command sequence
On the host whose key you want to publish:
ssh-keygen -r hostname.example.comThis prints one SSHFP line per host key file in /etc/ssh/. For a typical Ubuntu or Debian box, that is ssh_host_ed25519_key, ssh_host_ecdsa_key, and ssh_host_rsa_key. Output looks like:
hostname.example.com IN SSHFP 1 1 7c4b8e2c8a9d3f1b2e5a6c7d8e9f0a1b2c3d4e5f
hostname.example.com IN SSHFP 2 1 7c4b8e2c8a9d3f1b2e5a6c7d8e9f0a1b2c3d4e5f
hostname.example.com IN SSHFP 3 1 7c4b8e2c8a9d3f1b2e5a6c7d8e9f0a1b2c3d4e5f
hostname.example.com IN SSHFP 4 1 7c4b8e2c8a9d3f1b2e5a6c7d8e9f0a1b2c3d4e5fAdd these to the zone file. After a rndc reload or your equivalent, query the record:
dig SSHFP hostname.example.comYou should see the records. To verify DNSSEC validation, use delv or check that the AD (Authenticated Data) flag is set in the response.
On the client side, the verification is automatic if the SSH client is configured to use SSHFP. The OpenSSH client by default does not. Enable it per-host in ~/.ssh/config:
Host *.example.com
VerifyHostKeyDNS yesOr globally in /etc/ssh/ssh_config:
VerifyHostKeyDNS yesWith this set, the first connection to a new host in the verified zone will succeed without the manual yes prompt, because the SSHFP record validates the host key. A subsequent connection that presents a different key will be rejected, because the SSHFP record no longer matches.
Pitfalls to avoid
The biggest pitfall is regenerating host keys without updating SSHFP. Every time the OpenSSH package is reinstalled (or a tool like dpkg-reconfigure openssh-server runs), the host keys can be regenerated. If you forget to update SSHFP, every SSH connection will fail with a confusing error. The fix is to either disable host key regeneration in the OpenSSH config or make SSHFP updates part of the host provisioning flow.
The second pitfall is using the SHA-1 fingerprint type. The default output of ssh-keygen -r uses SHA-1. Modern SSH clients prefer SHA-256. Generate both:
ssh-keygen -r hostname.example.com -aThe -a flag generates both SHA-1 and SHA-256 records, which is what you want for compatibility with older clients.
The third pitfall is publishing SSHFP for the wrong key. If you only have a ssh_host_rsa_key and you publish an SSHFP for it, the client will accept only RSA host keys. If the server later offers an Ed25519 key, the client will reject the connection. The fix is to publish SSHFP for every key type the server offers.
Verifying the trust chain on the client
If you want to verify that SSHFP is actually working, enable verbose output on the SSH client:
ssh -v hostname.example.comIn the verbose output, look for lines like:
debug1: Server host key: ssh-ed25519 SHA256:...
debug3: verify_host_key_dns: matched SSHFP fingerprintThe matched SSHFP fingerprint line confirms that the DNSSEC-validated SSHFP record matched the host key the server presented. If you see a failed to match line, the host key has changed since the SSHFP record was published.
FAQ
Is the SHA-1 fingerprint type still safe?
The cryptographic hash is not the weak part of SSHFP. The trust chain is DNSSEC. If DNSSEC is working, the SSH client is verifying that the SSHFP record was published by the legitimate zone operator. SHA-1 in this role is fine for compatibility, but most operators now publish SHA-256 (-a flag) because the SHA-1 deprecation pressure has been mounting for years.
What if my DNS provider does not support SSHFP records?
Most authoritative DNS providers support SSHFP because the record type is in the IANA registry. If your provider does not, the SSHFP workflow does not work, and you have two options: switch DNS providers, or fall back to the standard known_hosts file. The standard flow is fine for most use cases.
Can I use SSHFP for client keys?
No. SSHFP is for server host keys only. The trust chain for a client’s authentication key is authorized_keys on the server, not DNS. The right way to manage client keys at scale is a configuration management tool (Ansible, Puppet, Chef) that distributes authorized_keys to the right servers.
Does the OpenSSH server need any configuration for SSHFP?
No. SSHFP is purely a client-side feature. The server presents its host key as normal. The client decides whether to verify that key against SSHFP, against the local known_hosts, or to require a manual confirmation.
What about Windows SSH clients?
The native Windows OpenSSH client (Windows 10 1809+ and Server 2019+) supports SSHFP and VerifyHostKeyDNS. The legacy PuTTY does not. If you are on PuTTY, the SSHFP workflow does not work and the standard known_hosts equivalent (the Windows registry under HKCU\Software\SimonTatham\PuTTY\SshHostKeys) is what you are stuck with.
Is there an equivalent for HTTPS?
Yes: DANE (DNS-based Authentication of Named Entities) and TLSA records. The mechanism is the same — publish a certificate fingerprint in DNS, validate the certificate against the fingerprint with DNSSEC as the trust anchor. The reason SSHFP is more widely deployed than DANE is that the SSH host key is simpler than the X.509 chain. Most HTTPS sites still rely on the CA model.
If you are sizing the infrastructure for the kind of project this post covers, the RunxBuild hosting calculator is the right place to model the line items. The compute, the memory, the storage, the bandwidth, the database - each one is a separate number, and the team’s mental model for the platform is the sum of those numbers. The RunxBuild dashboard is where the team sees the actual usage in one place.
Useful related references: