skip to content

With OpenSSH user certificates, what does sshd check before accepting a CA-signed key, and how do principals map a certificate to an account?

level: seniorimportance: should knowfreq 20%

answer

  1. trust the signer, not each key
  2. TrustedUserCAKeys
  3. -I, -n and -V when signing
  4. AuthorizedPrincipalsFile per account
  5. empty principals since 10.3

basics

~20 s

sshd accepts an OpenSSH user certificate when a trusted CA signed it, the current time is inside its validity window, a principal fits the account, its critical options are understood and allowed, and the client signs the session with the certified key.

solid answer

~50 s

An OpenSSH user certificate is the user's public key plus a key ID, principals, a validity window and options, all signed by a CA key, for example `ssh-keygen -s user_ca -I [email protected] -n sre -V -5m:+1d id_ed25519.pub`. With `TrustedUserCAKeys`, sshd trusts the CA instead of each key: it checks the CA signature, that it is a user certificate, the validity window, critical options such as `force-command` or `source-address`, and revocation via `RevokedKeys`. Principals then decide the account: by default the login name itself must be listed; with `AuthorizedPrincipalsFile` each account lists the principals it accepts, so `sre` can map to `deploy`. The client still signs the session identifier with the certified private key. Since OpenSSH 10.3 an empty principals section matches nothing through an authorized_keys `principals=` option, where it used to match any; `TrustedUserCAKeys` always refused it.

code

bash · 6 lines
bash
# CA signs alice's public key: log ID, role principal, one-day window
ssh-keygen -s /etc/ssh-ca/user_ca -I [email protected] \
    -n sre -V -5m:+1d ~/.ssh/id_ed25519.pub
# writes ~/.ssh/id_ed25519-cert.pub next to the key; inspect it
ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub
# on the server, /etc/ssh/principals/deploy lists: sre

go deeper

for a junior

Recall the idea: servers trust one CA key, and a user certificate is the user's public key signed by that CA with names and an expiry.

for a middle

Explain the fields and the checks: key ID, principals, validity, critical options, then TrustedUserCAKeys and the default rule that the account name must be a principal.

for a senior

Show how you would run it: role principals mapped by AuthorizedPrincipalsFile, one-day validity, key IDs in logs, a KRL for early revocation, and the 10.3 empty-principals change when auditing an older CA.

for a principal

Weigh what moves: certificates remove per-host key lists but concentrate risk in the CA key and the issuing service, so its protection, availability and audit trail become the real design.

## Why certificates With plain public keys every server must list every key it trusts in `authorized_keys`, and removing a person means finding every copy. An **OpenSSH user certificate** turns that around: servers trust one **CA key**, and the CA signs short-lived certificates for users. Choosing between pushed key files, a key-lookup command and certificates for a fleet is a decision covered by the material on running OpenSSH; this question is about what a certificate contains and how sshd verifies one. Host certificates, which let clients trust servers, belong to the material on key exchange and host keys. OpenSSH certificates are **not X.509**. The format is OpenSSH's own, described in the Internet-Draft draft-miller-ssh-cert, and the certificate travels in the public-key blob of an ordinary `publickey` request, which RFC 4252 allows. ## What a user certificate contains | Field | Set with `ssh-keygen` | What sshd does with it | |---|---|---| | public key | the `.pub` file being signed | the client must sign the session with the matching private key | | key ID | `-I` | written to the log, and usable for revocation | | serial number | `-z` | usable for revocation | | principals | `-n`, comma-separated | must match the account (see below) | | validity | `-V`, e.g. `-5m:+1d` | refused outside the window; the default is valid forever | | critical options | `-O force-command=...`, `-O source-address=...` | must be understood and enforced, or the certificate is refused | | extensions | `-O no-pty`, `-O no-port-forwarding`, ... | permissions; unknown ones are ignored | | signature key and signature | `-s` the CA key | must be a CA the server trusts | The CA signature covers every field above, so none of them can be edited after signing. ## How sshd verifies a certificate login 1. The client offers the certificate in a `publickey` request (algorithm names such as `[email protected]`). 2. sshd checks the **CA signature** and that the signing key is listed in `TrustedUserCAKeys`, or appears on an `authorized_keys` line marked `cert-authority`. 3. It checks the certificate is a **user** certificate and that now falls inside **valid after / valid before**. 4. It enforces the **critical options**: `source-address` must contain the client's address, and `force-command` replaces the requested command. 5. It checks **revocation**: `RevokedKeys` can name a plain key list or a KRL, which revokes certificates by serial or key ID. 6. It checks the **principals** against the target account. 7. Finally the client's **signature over the session identifier** must verify under the certified public key. The certificate alone is public; possession of the private key is still the proof. ## Mapping principals to accounts - With `TrustedUserCAKeys` and nothing else, **the account name itself must appear** among the certificate's principals. - With `AuthorizedPrincipalsFile`, for example `/etc/ssh/principals/%u`, the file for each account lists the principals it accepts, one per line. If `/etc/ssh/principals/deploy` contains `sre`, any certificate with the principal `sre` can log in as `deploy`. Role names as principals are what let a 400-person organisation grant access by role rather than by person. - `AuthorizedPrincipalsCommand` produces the same list from a program, run as `AuthorizedPrincipalsCommandUser`. - On an `authorized_keys` line marked `cert-authority`, the `principals="..."` option plays the same role for that one account; `AuthorizedPrincipalsFile` is not consulted for CAs trusted that way. ```ini # sshd_config: trust one user CA, map role principals per account TrustedUserCAKeys /etc/ssh/user_ca.pub AuthorizedPrincipalsFile /etc/ssh/principals/%u RevokedKeys /etc/ssh/revoked.krl ``` ## The OpenSSH 10.3 change Before OpenSSH 10.3, a certificate with an **empty principals section** was treated as matching **any** principal when trust came through an `authorized_keys` `principals=` option. A CA that issued one by mistake had issued a certificate valid for every account trusting that CA. Since 10.3 an empty principals section **never matches**. `TrustedUserCAKeys` was never affected: its man page says certificates that lack principals are not permitted at all. The same release made wildcard characters unsupported in user-certificate principals; they remain for host certificates. ## Operating it - **Short validity** does most of the revocation work: a one-day certificate stops working tomorrow even if nobody acts. - **Key IDs** make logs readable: sshd logs the ID, so `-I [email protected]` tells you who used a role principal. - **The CA key** becomes the most valuable secret in the system; whoever holds it can mint access for any principal servers accept. - `ssh-keygen -L -f id_ed25519-cert.pub` prints a certificate's principals, validity and options when a login fails.

  • How do you cut off one engineer's OpenSSH certificate before it expires?
    Revoke it in a KRL built with ssh-keygen -k, by serial number or key ID, and point RevokedKeys at that file on each server. Replace the file atomically: if RevokedKeys cannot be read, sshd refuses public-key logins for everyone. Short validity bounds the damage while revocation propagates.
  • Without AuthorizedPrincipalsFile, which principal must an OpenSSH user certificate carry to log in as deploy?
    deploy itself. With TrustedUserCAKeys alone, the target account name must appear in the certificate's principals. Mapping a role principal such as sre onto deploy needs AuthorizedPrincipalsFile or AuthorizedPrincipalsCommand on the server.
  • Does sshd contact the CA when a user presents an OpenSSH certificate?
    No. Verification is offline: sshd checks the CA signature against the public CA key it already trusts, the validity window, options, principals and its local revocation list. That is why short lifetimes and a distributed KRL matter, since there is no online status check.

A user certificate works like a conference badge printed at the registration desk: the door attendant keeps no guest list, only checks the desk's stamp, the role and dates printed on the badge, and that the person wearing it matches the photo.

  • sshd contacts the CA at each login to check the certificate is still valid.
  • A user certificate with no principals is valid for every account on a current OpenSSH.
  • OpenSSH user certificates are X.509 certificates like those used for TLS.
  • Holding the certificate file alone is enough to log in.
  • A certificate signed without -V expires after one day by default.

Assumes OpenSSH 10.5; since 10.3 an empty certificate principals section never matches via an authorized_keys principals= option (it used to match any), and user-certificate principals no longer support wildcards.