With OpenSSH user certificates, what does sshd check before accepting a CA-signed key, and how do principals map a certificate to an account?
answer
- trust the signer, not each key
- TrustedUserCAKeys
- -I, -n and -V when signing
- AuthorizedPrincipalsFile per account
- empty principals since 10.3
basics
~20 ssshd 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 sAn 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# 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: srego deeper
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.
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.
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.
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.