SSH Client and Host Onboarding Guide

Quickest

sudo -iu akadmin vw unlock

n00b

cat /etc/ssh/ssh_host_ed25519_key

vim ~/.ssh/authorized_keys
# type-y type-y

n00b

ssh -i /etc/ssh/ssh_host_ed25519_key ul
# test ^
cat /etc/ssh/ssh_host_ed25519_key.pub | ssh ul "sudo sign-host-key n00b -l n00b0x" | sudo tee /etc/ssh/ssh_host_ed25519_key-cert.pub
sudo chmod 644 /etc/ssh/ssh_host_ed25519_key-cert.pub
printf 'HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub\n' | sudo tee /etc/ssh/sshd_config.d/10-cert.conf
sudo sshd -T -f /etc/ssh/sshd_config | grep -q HostCertificate || echo fail
sudo systemctl reload sshd

UNLOCK VAULTWARDEN

The CA signing keys reside in Vaultwarden and are kept in volatile memory for 1 hour once unlocked. Before onboarding, log into ul and unlock the vault:

sudo -iu akadmin vw unlock

WORKFLOW 1: ONBOARDING A NEW HOST (Server Host Certificate)

Host certificates allow clients to verify the authenticity of a server automatically without manual fingerprint checks ("The authenticity of host ... can't be established").

1. Generate Host Keypair on New Machine

On the machine being onboarded "n00b", generate its standard Ed25519 host key (if it does not already exist):

sudo ssh-keygen -t ed25519 -f /etc/ssh/ssh_host_ed25519_key -N ""

2. Out-of-Band Bootstrap & Verification

Verify it using authorized_keys first:

Copy the n00b's public key text (/etc/ssh/ssh_host_ed25519_key.pub) out-of-band
Add it to ~/.ssh/authorized_keys on ul.
Test SSH connectivity from the new host to ul:
```
ssh -i /etc/ssh/ssh_host_ed25519_key ul
```

Verified!

3. Mint Signed Host Certificate

From the new host, stream the public key over that verified SSH connection directly into sign-host-key:

cat /etc/ssh/ssh_host_ed25519_key.pub | ssh ul "sudo sign-host-key bmo95 -l studio-pc" | sudo tee /etc/ssh/ssh_host_ed25519_key-cert.pub

Custom Principals: To specify custom DNS names or IP addresses:

cat /etc/ssh/ssh_host_ed25519_key.pub | ssh -t ul "sudo sign-host-key danknasty danknasty,danknasty.drheck.dev,10.0.0.1,fd77:7777:5010::1" | sudo tee /etc/ssh/ssh_host_ed25519_key-cert.pub

Set file permissions on the new host:

sudo chmod 644 /etc/ssh/ssh_host_ed25519_key-cert.pub

4. Configure sshd on the New Host

Add the host certificate to the SSH daemon configuration on the new host (/etc/ssh/sshd_config or /etc/ssh/sshd_config.d/10-cert.conf):

HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub

Reload the SSH daemon:

sudo systemctl reload sshd

5. De-provision Bootstrap Key

Remove the temporary bootstrap entry from ~/.ssh/authorized_keys on ul.

WORKFLOW 2: ONBOARDING A NEW USER (Client User Certificate)

User certificates allow clients to log into servers without putting per-user public keys in .ssh/authorized_keys.

1. Generate User Keypair on Client Workstation

On your laptop or workstation:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "workstation-label"

2. Out-of-Band Bootstrap & Verification

Copy ~/.ssh/id_ed25519.pub out-of-band and temporarily append it to ~/.ssh/authorized_keys on ul.
Confirm login works:
```
ssh ul
```

3. Mint Signed User Certificate

From your client workstation, pipe your public key into sign-user-key:

cat ~/.ssh/id_ed25519.pub | ssh -t ul "sudo sign-user-key <ldap_username>" > ~/.ssh/id_ed25519-cert.pub
chmod 644 ~/.ssh/id_ed25519-cert.pub

Note: The principal <ldap_username> must exactly match the Authentik/LDAP username on ul.

4. De-provision Bootstrap Key

Remove the raw public key from ~/.ssh/authorized_keys on ul.

5. Verify Certificate Authentication

ssh -v ul

Confirm the server accepts the certificate:

Server accepts key: pkalg ssh-ed25519-cert-v01@openssh.com

CLIENT CONFIGURATION: TRUSTING THE HOST CA

To ensure client workstations trust all servers signed by the DrHeck Host CA without fingerprint prompts, add this line to /etc/ssh/ssh_known_hosts (system-wide) or ~/.ssh/known_hosts:

@cert-authority * ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIC0m1wzW2e50529d+E3iA7x8iM3Q8qS5q7iVjGvF8e7d

(Replace with the actual public key from /etc/ssh/drheck_ca_host_key.pub).

QUICK REVOCATION REFERENCE

Every signed key is automatically archived in /etc/ssh/ca_inventory/.

List all signed keys:
```
revoke-key --list
```
Revoke a key immediately:
```
sudo revoke-key <label>
```