SSH Host Certificates

1. The TOFU Problem

Every SSH user has seen this:

The authenticity of host 'server01.example.com (10.0.1.50)' can't be established.
ED25519 key fingerprint is SHA256:xK3rV9mPqL2nB8wY5tH7jU4cF6gA1dS0zX9oN3iE2qM.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Be honest: When was the last time you actually verified that fingerprint?

This is TOFU - Trust On First Use. The security model is:

1. First connection: blindly trust whatever server responds
2. Future connections: warn if the key changes

The problems with TOFU:

2. How Host Certificates Work

The solution mirrors how TLS handles server identity:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │     │     CA      │     │   Server    │
│(trusts CA)  │     │  (signs)    │◀────│ (has cert)  │
└─────────────┘     └─────────────┘     └─────────────┘
       │                                       │
       │  1. Connect to server                 │
       │──────────────────────────────────────▶│
       │                                       │
       │  2. Server presents host certificate  │
       │◀──────────────────────────────────────│
       │                                       │
       │  3. Client verifies cert against CA   │
       │     ✓ Valid? Connect!                 │
       │     ✗ Invalid? Reject!                │

What's happening:

1. Server's host key is signed by a CA → creates host certificate
2. Client trusts the CA (configured once)
3. On connection, client verifies the server's certificate
4. Valid certificate from trusted CA = automatic trust
5. No fingerprint prompt. No known_hosts entry needed.

3. Anatomy of a Host Certificate

Host certificates contain fields that identify the server:

→ See our SSH Certificate Anatomy demo to explore these fields interactively.

4. Signing a Host Certificate

Sign the server's existing host key:

ssh-keygen -s /path/to/host_ca \
  -I "server01.example.com-20250114" \
  -h \
  -n server01.example.com,server01,10.0.1.50 \
  -V +52w \
  /etc/ssh/ssh_host_ed25519_key.pub

Flag breakdown:

Output: Creates /etc/ssh/ssh_host_ed25519_key-cert.pub

5. Server Configuration

Tell sshd to present the certificate:

# /etc/ssh/sshd_config

# Present this certificate to connecting clients
HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub

Restart sshd:

systemctl restart sshd

Multiple key types? Add multiple HostCertificate lines:

HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub
HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub

6. Client Configuration

Clients need to trust the CA. Two options:

This says: "Trust any host certificate signed by this CA for hosts matching *.example.com"

Pattern matching:

7. The Complete Picture: User + Host Certificates

With both certificate types deployed:

┌──────────────┐                      ┌──────────────┐
│    Client    │                      │    Server    │
│              │                      │              │
│ Trusts:      │                      │ Trusts:      │
│ • Host CA    │◀────── TLS-like ────▶│ • User CA    │
│              │      mutual trust    │              │
│ Has:         │                      │ Has:         │
│ • User cert  │                      │ • Host cert  │
└──────────────┘                      └──────────────┘

8. Use Cases

Host certificates shine in these environments:

9. Deployment Strategy

Rolling out host certificates is low-risk:

10. Validity Periods and Renewal

Host certificates can have longer validity than user certificates:

Renewal approaches:

Example: Renewal check script

#!/bin/bash
CERT="/etc/ssh/ssh_host_ed25519_key-cert.pub"
EXPIRY=$(ssh-keygen -L -f "$CERT" | grep "Valid:" | awk '{print $5}')
EXPIRY_EPOCH=$(date -d "$EXPIRY" +%s)
NOW_EPOCH=$(date +%s)
DAYS_LEFT=$(( (EXPIRY_EPOCH - NOW_EPOCH) / 86400 ))

if [ $DAYS_LEFT -lt 14 ]; then
    echo "Host certificate expires in $DAYS_LEFT days - renewal needed"
    # Trigger renewal process
fi

11. Troubleshooting

Common issues and solutions:

Debug from client side:

ssh -vvv user@server 2>&1 | grep -i "host cert"

Look for:

• Server host certificate: ... - Server is presenting certificate
• Host certificate: ... CA ... - Client is checking against CA

Verify certificate on server:

ssh-keygen -L -f /etc/ssh/ssh_host_ed25519_key-cert.pub

Check principals list and validity dates.

12. Host Certificates + Configuration Management

Deploying at scale with Ansible, Puppet, or similar:

Ansible example:

# Sign host key (run from CA machine)
- name: Sign host certificate
  command: >
    ssh-keygen -s /etc/ssh/host_ca
    -I "{{ inventory_hostname }}-{{ ansible_date_time.date }}"
    -h
    -n {{ inventory_hostname }},{{ ansible_hostname }},{{ ansible_default_ipv4.address }}
    -V +52w
    /etc/ssh/ssh_host_ed25519_key.pub
  delegate_to: ca_server

# Deploy certificate to host
- name: Deploy host certificate
  copy:
    src: "/etc/ssh/certs/{{ inventory_hostname }}-cert.pub"
    dest: /etc/ssh/ssh_host_ed25519_key-cert.pub
    mode: '0644'
  notify: restart sshd

# Configure sshd
- name: Add HostCertificate directive
  lineinfile:
    path: /etc/ssh/sshd_config
    line: "HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub"
  notify: restart sshd

FAQ

Related Guides