Device Passport

Threat model

This page is for people deciding whether to use device-passport: device owners, the teams that run a CA, and buyers who need to know what a "passing" device really means. It restates section 4 of the design in plain language and describes what the Phase 1 code actually does.

Status: Phase 1 (v0). Every answer is agent-reported. Device keys are software keys until the hardware backends land (milestone M6). Read Residual risks in Phase 1 before you rely on this for anything.

The short version

device-passport lets an SSH server admit only devices that say they meet a posture bar: disk encrypted, OS patched, firewall on, and so on. The device signs its answers with its own key. A team-run CA checks the answers and, if they pass, issues an SSH certificate that lasts 10 minutes.

It catches honest mistakes. It does not catch a liar with root.

This is the same model that compliance agents such as Vanta or 1Password Device Trust work under. Auditors accept it for SOC 2. We say it plainly so nobody mistakes it for more.

What "agent-reported" means

Every answer the device gives carries an assurance level. Phase 1 has one level in use: agent-reported.

An agent-reported answer means: the device-passport agent on this specific device says so.

It proves:

It does not prove:

The CA does not trust the assurance label the device writes. It works the label out itself. Until evidence from a trusted issuer is checked (Phase 2), the CA counts every result as agent-reported, whatever the device claims. The CA refuses to start with min_assurance = "hardware-backed" for the same reason.

Hardware-backed answers come later (Phase 2). They are signed by Apple or a TPM and checked by an evidence issuer. They narrow the gap: an attacker cannot forge Apple's or a TPM's signature over the boot state. Runtime state above the boot chain stays self-reported even then.

What device-passport will never do

These are design rules (the anti-goals in section 3 of the design). If any of them becomes true, the design has failed, even if it works.

What the CA learns, and what it does not

At enrollment (dp enroll), the CA learns:

At each certificate request, the CA learns:

The CA does not learn:

One thing is shared: the device key. The same public key is registered with every CA you enroll with, and it is in every SSH certificate. Two organisations that compare notes can tell that the same device enrolled with both. Every SSH server you log in to sees the key too.

The CA's challenge endpoint gives the same refusal for "unknown device", "revoked", "bad signature" and "principal not allowed". Another organisation cannot use your CA to find out whether a device is enrolled there.

Who can do what

A compromised CA

Someone who controls a team's CA (its host, or its key files) can:

They cannot:

To stop trusting a CA, revoke its grant on the device (dp grants revoke <grant_id>). The agent stops answering at once.

A compromised device (malware without root)

Malware running as you, but not root, can:

It cannot:

Other local users (not you, not root) can read the predicate outcomes with dp status. They cannot use the key, see grants, or read the log.

A malicious root user (or a dishonest owner)

Root can make the device say anything. Root can:

This is the main limit of the whole approach, and it is stated in the design. Hardware keys (M6) stop the key copying. Hardware-backed evidence (Phase 2) stops lies about the boot state. Nothing in this design stops a root user lying about runtime settings.

A stolen laptop

If the thief gets the laptop unlocked and logged in, they can use your SSH access like you can. Enrollment is already done, so no SSO login is needed for each certificate. Revoke the device on the CA at once (dpass-ca devices revoke <device_id>). It gets no new certificates after that. A certificate it already has stays valid until it expires (at most cert_ttl, 10 minutes by default).

If the laptop is locked or off:

A network attacker

The device only talks to a CA over HTTPS (plain HTTP is allowed only to 127.0.0.1 or [::1], for testing). The CA must sit behind a TLS terminator. Beyond TLS:

A network observer can still see that a device talks to a CA (DNS, TLS server name) and when.

How access ends

Action Takes effect What still works
dpass-ca devices revoke <device_id> next challenge or certificate request certificates already issued, until they expire
dpass-ca people revoke <email> next request, for every device of that person same as above
dp grants revoke <grant_id> (on the device) next challenge from that CA same as above
Device stops passing a predicate next certificate fetch the cached certificate, until it expires

dpass-ca people revoke also blocks the person's email and principal key. A recreated SSO account with the same email cannot register again.

Three things outlive revocation:

  1. Issued certificates. OpenSSH does not ask the CA whether a certificate is still good. A certificate is valid until it expires. That is why the default lifetime is 10 minutes. dp-ssh-agent reuses a cached certificate while it has more than 60 seconds left.
  2. Open SSH sessions. sshd checks the certificate at login only. A session that is already open stays open after the certificate expires. So does an SSH connection shared through ControlMaster.
  3. Posture changes. The device is checked when a certificate is issued, not during the session.

Operators can close the first gap with OpenSSH's own RevokedKeys. See Operating the CA.

Host scoping

The ssh-agent protocol does not tell the agent which server ssh is connecting to. If one agent socket served every CA's certificate, every server would see every organisation's certificate, and connecting to one organisation's server would contact every CA.

So dp-ssh-agent opens one socket per ssh.toml entry (one per CA and principal), and dp ssh setup points each entry's Host patterns at that entry's socket with IdentityAgent. A server that matches one organisation's patterns sees only that organisation's certificate (and the raw device key), and only that CA is contacted. The patterns are yours to set. A pattern that is too broad shows that certificate to more servers.

Residual risks in Phase 1