How it works
Device Passport adds one decision to an SSH login: should this device get a certificate right now? Everything else is stock OpenSSH.
The login, step by step
- Enrollment, once. A person signs in to the team's CA through SSO. The CA says which checks it wants to ask. The person grants them, and the device registers its public key.
- Challenge. When the person runs
ssh,dp-ssh-agentasks the CA for a challenge. It is valid for 60 seconds and the CA accepts it once. - Answer.
dpassdcollects fresh facts, evaluates the granted checks and signs the answers with the device key. The answer names this CA, so it cannot be replayed to another organization. - Decision. The CA compares the answers to the policy for the requested environment. If one fails, it refuses and names it.
- Certificate. The CA issues an OpenSSH certificate that lasts 10
minutes by default.
sshdaccepts it throughTrustedUserCAKeys.
The private key never leaves dpassd, or the hardware that holds it.
Grants: the owner decides
A grant is the owner's permission for one CA to ask a named list of checks.
The agent refuses any question outside a grant. Grants expire, carry a rate
limit (120 questions an hour by default), and can be revoked on the device
at once with dp grants revoke.
Every question and answer is written to a local hash-chained log that the
owner can read with dp log.
One device, many organizations
A device can enroll with any number of CAs. Each CA has its own key and its own grant, and sees only the answers it was granted. One organization's access never depends on another organization's infrastructure.
What the SSH check shares
For SSH certificate issuance, the agent answers challenges fetched by its SSH agent. Each check returns yes, no or unknown. Separate security requests have their own consent flow. Device Passport grants no authority to change, isolate or wipe the device.
Revocation
Revoking a device or a person takes effect at the device's next request,
so no new certificate is issued. Certificates already issued run out
within their lifetime. The CA also serves a revocation list (/v1/krl)
that sshd can load. Details are in
Operating the CA.
Beyond the certificate
- Hardware keys. An environment can require that the certificate go to a Secure Enclave or YubiKey key. See Hardware keys.
- Hardware evidence. The attestation service checks TPM quotes inside a TEE and gives the CA a signed verdict. See the attestation service design.
- Canary tokens. Decoy keys that reveal a laptop whose files were read. See the canary tokens specification.
- A signed record. Every state change at the CA is a signed, hash-chained event. See Event stream.
The wire format for every message is in Protocol v0.