Device Passport

Operating the CA

dpass-ca is the SSH certificate authority a team runs for itself. It registers people's devices through your SSO (OIDC), checks each device's posture answer, and issues short-lived OpenSSH user certificates. Stock sshd trusts it through TrustedUserCAKeys. No sshd patches or plugins.

This guide covers setup, the config file, your identity provider, sshd, revocation and backups. For what the posture check proves and what it does not, read the threat model first.

Status: Phase 1 (v0). Every posture answer is agent-reported, and device keys are software keys until milestone M6. Wire formats may change before Phase 2.

Contents

How it fits together

  1. A person runs dp enroll https://ssh-ca.example.com on their device. They sign in through your identity provider in a browser. The CA maps their identity to SSH principals, records the device's public key, and asks the device for a grant: a list of posture questions (predicates) the CA may ask.
  2. When the person runs ssh, dp-ssh-agent on their device asks the CA for a challenge, gets the device's signed answer from dpassd, and posts it to the CA.
  3. The CA checks the answer against the environment that governs the principal asked for. If every required predicate is true, it signs an OpenSSH certificate for the device key, valid for cert_ttl (10 minutes by default).
  4. sshd accepts the certificate because it trusts the CA's public key.

The CA serves five HTTP endpoints, all POST with JSON bodies: /v1/register/start, /v1/register/finish, /v1/register/grant, /v1/challenge and /v1/cert.

Install

There are no published packages yet. Build from source with the Rust toolchain pinned in rust-toolchain.toml. The build needs OpenSSL's development files (for WebAuthn attestation); on Debian or Ubuntu:

sudo apt-get install build-essential pkg-config libssl-dev
cargo install --locked --path crates/dp-ca

This installs the dpass-ca binary. SQLite is compiled in. packaging/ca/ has systemd units for the CA and the console and a container image; see Packaging.

Set up a CA

1. Generate the keys

sudo dpass-ca init --dir /etc/dpass-ca

--dir defaults to /etc/dpass-ca. The directory is created with mode 0700 if missing. init writes six files and refuses to overwrite any that exist:

File What Mode
ssh_ca_ed25519 SSH CA private key (Ed25519, OpenSSH format). Signs certificates. 0600
ssh_ca_ed25519.pub Its public key line, for TrustedUserCAKeys. 0644
audience_ed25519 Audience private key (raw Ed25519 seed). Signs challenges. Every grant names its public half. 0600
audience_ed25519.pub Audience public key, base64url. 0644
event_ed25519 Event key (raw Ed25519 seed). Signs the event stream; set event_key to it. 0600
event_ed25519.pub Event public key, base64url. Pin it wherever the stream is checked. 0644

It prints the audience and event keys and, on stdout, the line to add to sshd's TrustedUserCAKeys file.

Run as root, init leaves the files owned by root. Hand the directory to the user that runs the CA before starting it:

sudo chown -R dpass-ca:dpass-ca /etc/dpass-ca

dpass-ca serve refuses to load a private key file that group or others can read or write.

2. Write the config

Copy crates/dp-ca/dpass-ca.example.toml to /etc/dpass-ca/dpass-ca.toml (the default --config path) and edit it. See the reference below.

Put the OAuth client secret in the file named by oidc.client_secret_file. Leading and trailing whitespace is trimmed. Make it readable only by the user that runs dpass-ca.

Create the database's directory. serve creates and migrates the SQLite file itself, but not its parent directory:

sudo mkdir -p /var/lib/dpass-ca

3. Check it

dpass-ca check-config --config /etc/dpass-ca/dpass-ca.toml

It prints <path>: ok (N environment(s), N predicate(s) requested, cert_ttl 10m) or the first error. It checks the file only. It does not load keys or contact the identity provider.

4. Serve

dpass-ca serve --config /etc/dpass-ca/dpass-ca.toml

At startup serve reads the client secret, loads both keys, opens (and creates or migrates) the database, and fetches the identity provider's discovery document. If any of these fails, it exits. It stops cleanly on Ctrl-C or SIGTERM.

The service speaks plain HTTP. Put it behind a TLS terminator (nginx, Caddy, a load balancer) that serves public_url. Devices refuse a CA URL that is not https://, except http://127.0.0.1 and http://[::1] for local testing.

Run one serve process per CA. Registration sessions and outstanding challenges live in that process's memory. A second instance behind a load balancer would not know about the first one's. A restart only means in-flight enrollments start over and devices fetch a new challenge.

5. Tell your users

Users need the CA's public_url and the principal they should use. Their side is in the README.

Config file reference

TOML. Durations use humantime form: "90s", "10m", "24h", "180d". Unknown keys are an error, so a typo cannot silently weaken policy.

Top level

Key Required Default Meaning
listen no "127.0.0.1:8443" Address and port the HTTP service binds.
public_url yes The CA's public base URL, as devices see it (e.g. "https://ssh-ca.example.com"). Devices sign it into their registration and challenge requests, and the CA refuses requests made for any other URL (trailing slashes aside).
ssh_ca_key yes Path of the SSH CA private key.
audience_key yes Path of the audience private key.
database yes Path of the SQLite file.
cert_ttl no "10m" Lifetime of issued certificates. Must be more than zero. This is also the longest a revoked device keeps access; see revocation timing.

[oidc]

Key Required Default Meaning
issuer yes Issuer URL. The CA fetches <issuer>/.well-known/openid-configuration. Must be https (plain http only on a loopback IP, for tests).
client_id yes OAuth client id.
client_secret_file yes File holding the OAuth client secret.
principal_claim no "email" ID token claim whose value is looked up in [principals]. Must be a string claim.

[principals]

A table from the value of principal_claim to the SSH principals that person may get certificates for:

[principals]
"alice@example.com" = ["alice", "deploy"]
"bob@example.com" = ["bob"]

A person whose claim value is not listed cannot register a device. The CA reads this table on every challenge, so removing a person (and restarting the CA) stops their certificates. Use dpass-ca people revoke for an immediate, permanent block.

A principal must also be listed in an [[environment]] to be usable. A principal no environment governs is refused.

[grant_request]

What the CA asks each device to grant at enrollment. The user sees this on the consent screen.

Key Required Default Meaning
org no public_url Organisation name shown on the consent screen and written into the grant.
predicates yes Predicates the CA may ask about. Each must be in the registry, with a parameter from the registry's fixed buckets (for example os_patched_within:14d, screen_lock_within:5m).
lifetime no "180d" How long the grant lasts. After it expires the device must enroll again.
rate_per_hour no 120 Most questions per hour the device will answer under the grant.

The CA also asks for a freshness bound of 60 seconds (the challenge lifetime). The device declines rather than answer with older facts.

Changing grant_request affects only enrollments made after the change. If you add a predicate that an environment requires, devices enrolled earlier do not have it in their grant. They are declined until the person runs dp enroll again.

[[environment]]

Policy per group of principals. Repeat the table for each environment.

Key Required Default Meaning
name yes Name for logs and errors. Must be unique.
principals yes SSH principals this environment governs. Must not be empty. A principal may appear in only one environment.
min_assurance no "agent-reported" Minimum assurance of each required result. Only "agent-reported" is accepted in Phase 1; "hardware-backed" is a config error until hardware evidence is checked.
require no [] Predicates that must be true. Each must also be in grant_request.predicates, or the config is rejected.
trusted_issuers no [] Evidence issuer keys. Reserved for Phase 2; not used yet.

A required predicate fails if the device reports false or unknown, or leaves it out. Every failing predicate is reported back to the device and logged, not just the first.

Platform matters. A predicate that does not exist on a platform is always unknown there, so it always fails: sip_enabled and kexts_disallowed on Linux, kernel_lockdown on macOS. Do not require them in an environment that Linux (or macOS) devices use.

Do not require ssh_key_hardware_bound in Phase 1. Every Phase 1 device uses a software key, so it is always false. An environment that requires it denies every certificate. (The example config requires it in production. Remove it there until hardware keys ship in M6.)

A config that works in Phase 1

listen = "127.0.0.1:8443"
public_url = "https://ssh-ca.example.com"
ssh_ca_key = "/etc/dpass-ca/ssh_ca_ed25519"
audience_key = "/etc/dpass-ca/audience_ed25519"
database = "/var/lib/dpass-ca/ca.sqlite"
cert_ttl = "10m"

[oidc]
issuer = "https://accounts.google.com"
client_id = "1234-abc.apps.googleusercontent.com"
client_secret_file = "/etc/dpass-ca/oidc_secret"

[principals]
"alice@example.com" = ["alice"]
"bob@example.com" = ["bob", "deploy"]

[grant_request]
org = "Example Corp"
predicates = ["disk_encrypted", "os_patched_within:14d", "firewall_enabled",
              "screen_lock_within:5m"]

[[environment]]
name = "production"
principals = ["alice", "bob", "deploy"]
require = ["disk_encrypted", "os_patched_within:14d", "firewall_enabled"]

Requiring a hardware token key

By default a certificate is issued to the device key. An environment can instead require that the certificate go to a separate key whose hardware vouches for how it is used: a Secure Enclave key (App Attest), or a YubiKey PIV key. The user-facing setup is in yubikey-piv.md.

[key_attest]

Opt in to each token source:

[key_attest]
piv = true    # accept YubiKey PIV attestations
Key Default Meaning
piv false Accept YubiKey PIV attestations at /v1/key/enroll. The chain must end at one of Yubico's two pinned roots ("Yubico PIV Root CA Serial 263751" and "Yubico Attestation Root 1"), through intermediates Yubico publishes. Preview-device CAs are refused, and so is a chain that is expired at the CA's clock.
extra_roots none A PEM file of further roots to trust. For tests only: it replaces nothing, but anything it names can vouch for any key.

Without piv = true, POST /v1/key/nonce and POST /v1/key/enroll answer disabled. Only P-256 keys are accepted in v0 (unsupported_key_type).

[environment.<name>.key]

A key table on an [[environment]] says what the key behind each certificate must prove. Write it inline:

[[environment]]
name = "production"
principals = ["alice", "bob"]
require = ["disk_encrypted", "os_patched_within:14d"]
key = { sources = ["yubikey-piv"], presence = "every", consent = ["pin-always", "pin-session"] }
Key Meaning
sources Allowed sources: app-attest, yubikey-piv. Empty: any.
presence Least physical presence per signature: none, cached (a touch covers about 15 s) or every. Orders every > cached > none.
consent Accepted consent values: pin-always, pin-session, biometry-current, biometry-any, biometry-session, user-presence, passcode, none. A stricter value satisfies a looser one. Empty: any.
vouched_by Accepted vouched-by values: hardware, vendor, app. A YubiKey is vendor. Empty: any.

require_se_key = true still works and means key = { sources = ["app-attest"] }. Setting both is a config error.

With a key table, a request for the device key is denied key_required. A token key the person has not enrolled (or that another person enrolled) is denied key_not_enrolled; one revoked with dpass-ca keys revoke is denied key_revoked; one whose attested policy falls short is denied key_policy_unmet, naming the field (presence, consent, sources or vouched_by). The same table applies at login.

A YubiKey PIV key maps to a policy like this:

Key's PIN policy consent Key's touch policy presence
never none never none
once per session pin-session cached (15 s) cached
always pin-always always every

Any other policy byte is never guessed at: the enrollment is refused (bad_attestation). That includes the YubiKey Bio values, until Yubico documents how they appear in an attestation.

What the certificate says

A certificate issued to a token key carries three extensions, which sshd can match with AuthorizedPrincipalsCommand or log:

The token's serial number is kept for admins and is never put in a certificate, an event or an API response.

Enrollment is per person

A token key is enrolled by a person's device (dp keys enroll-piv) and then works from any of that person's devices. A key enrolled by one person is refused for another (key_enrolled_elsewhere), and a key that is a device's own Secure Enclave key is refused (key_is_device_key). Enrolling again replaces the old enrollment. Revoking a person revokes their token keys.

Identity provider setup

What the CA needs from any provider

Google Workspace

  1. In the Google Cloud console, open APIs & Services โ†’ OAuth consent screen. Choose Internal, so only accounts in your Workspace can sign in.
  2. Open Credentials โ†’ Create credentials โ†’ OAuth client ID. Choose application type Desktop app. Google accepts loopback redirects on any port for this type, and you do not register a redirect URI.
  3. Copy the client ID into oidc.client_id. Save the client secret in the client_secret_file.
  4. Set oidc.issuer = "https://accounts.google.com".
  5. Keep principal_claim = "email". Google sets email_verified.

The CA does not check the Workspace domain (hd claim) itself. Only the emails you list in [principals] can register, and an Internal consent screen keeps other Google accounts out.

Okta

  1. In the Okta admin console, create an app integration: OIDC - OpenID Connect, application type Native Application.
  2. Grant type: Authorization Code. Turn on Require PKCE.
  3. Client authentication: Client secret. The CA always sends one.
  4. Sign-in redirect URI: http://127.0.0.1/cb. See the warning below.
  5. Assign the app to the people or groups who may enroll devices.
  6. Set oidc.issuer to your authorization server. For the org server that is https://<your-org>.okta.com; for a custom one, for example https://<your-org>.okta.com/oauth2/default. The CA appends /.well-known/openid-configuration.
  7. Keep principal_claim = "email". With the email scope Okta includes email_verified. Check that your users' emails are verified in Okta, or their logins are refused.

Warning: dynamic ports. dp enroll uses a different loopback port on every run. Okta's developer forum has said Okta does not follow RFC 8252's "any port" rule for loopback redirects, which would make the redirect fail with a mismatch. We have not yet tested enrollment against a live Okta tenant. Test one enrollment before rolling out. If it fails on the redirect URI, Okta cannot be used with this version of dp enroll.

sshd setup

Do this on every server that should accept device-passport certificates.

Trust the CA

Copy ssh_ca_ed25519.pub (or the line dpass-ca init printed) to the server, then in sshd_config:

TrustedUserCAKeys /etc/ssh/dpass_ca.pub

The file may hold several CA lines, one per line.

Say which principals may log in as which user

Every certificate carries exactly one principal: the one the device asked for, if the person has it and an environment governs it.

Without AuthorizedPrincipalsFile, sshd accepts a certificate only if one of its principals equals the target user name. So a certificate for principal alice logs in as user alice.

To map principals to accounts yourself, use AuthorizedPrincipalsFile:

AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u
# Let principals "alice" and "deploy" log in as user "deploy".
printf 'alice\ndeploy\n' | sudo tee /etc/ssh/auth_principals/deploy

Two things we verified in the OpenSSH spike:

Reload sshd after changing its config.

To have sshd ask the CA again at every login, not only when the certificate was issued, see Login checks and canaries on a server. Note that those checks require the account to be one of the certificate's principals, so they do not follow an AuthorizedPrincipalsFile mapping.

What a certificate looks like to sshd

Field Value
Key the device's ecdsa-sha2-nistp256 key
Type user
Key ID dp:<device_id>:<email> (shows in sshd's log)
Serial from the CA's database; matches dpass-ca certs list
Principals the one principal asked for
Valid from 30 seconds before issue until cert_ttl after
Extensions permit-pty, permit-port-forwarding

Agent forwarding, X11 forwarding and ~/.ssh/rc are not permitted. There are no critical options (no force-command, no source-address).

Admin commands

Every command reads the config (--config, default /etc/dpass-ca/dpass-ca.toml) to find the database. They are safe to run while serve is running. They fail if the database does not exist yet, so start serve once first. Add --json to the list commands for JSON output.

dpass-ca devices list [--json]
dpass-ca devices revoke <device_id>
dpass-ca people list [--json]
dpass-ca people revoke <email>
dpass-ca people add-email <person-email> <commit-email>
dpass-ca people remove-email <commit-email>
dpass-ca people emails <person-email>
dpass-ca keys list [--json]
dpass-ca keys revoke <key_id>
dpass-ca certs list [--since 24h] [--json]

There is no command to undo a revocation. A revoked device cannot register again with the same key. A revoked person stays revoked.

Canary tokens

A canary is a decoy SSH key that opens nothing. The CA offers it to enrolled laptops, and dp canaries place puts it in ~/.ssh with a matching ~/.ssh/config entry after the owner agrees. If anyone ever offers that key to one of your servers, someone has read that laptop's files: the CA records a canary_tripped security alert and, by default, revokes the laptop. Design: docs/superpowers/specs/2026-11-15-canary-tokens-design.md.

1. Offer canaries in dpass-ca.toml:

[canaries]
on_trip = "revoke_device"        # default; "record" only alerts

[[canaries.ssh_key]]
id = "deploy"                    # stable offer id
file = "id_ed25519_deploy"       # written under ~/.ssh (never a .pub)
host_alias = "deploy-prod"       # Host alias in ~/.ssh/config
hostname = "deploy.internal.example.com"   # a real server running the hook
user = "deploy"

Point hostname at a server that has the hook below, so a thief who tries the key is seen. Every field is a single token of letters, digits, ., _ or -.

2. Add the hook to your servers. On each server already set up for login checks (dpass-login init, registered with dpass-ca hosts add; the full steps, file permissions and pitfalls are in Login checks and canaries on a server), add to sshd_config, before any Match block:

AuthorizedKeysCommand /usr/libexec/dp-login-check --canary-key %u %t %f
AuthorizedKeysCommandUser dpass-login

sshd runs the command for public keys it is offered. The command never prints a key, so it never lets anyone in. It reports the key's fingerprint to the CA in the background, signed with the host key, and returns at once, so logins do not wait on the CA. The CA keeps nothing about keys that are not canaries. A server without the hook simply rejects the canary without reporting it.

3. Laptops place them. Owners run dp canaries to see what is offered, dp canaries place to review and place each one, and dp canaries remove to take them off again (the CA is told).

Watching them:

dpass-ca canaries list [--json]          # placed canaries, live and retired
dpass-ca canaries trips [<id>] [--json]  # every trip: host, login tried, time
dpass-ca canaries retire <id>            # it never trips again
dpass-ca alerts list                     # trips show as "Canary token used"

The admin console has the same view on its Canaries tab: each canary's status (watching, tripped, retired), the device and owner, every trip with the server and login name tried, and a Retire button. Retiring from the console is logged under the admin who did it. The JSON forms are GET /admin/v1/canaries and GET /admin/v1/canary_trips.

dp enroll offers the CA's canaries right after a device enrolls, with a separate yes for each one. dp enroll --yes never places a canary; it only says that dp canaries place is available.

Only a report signed by a registered host counts as a trip, so nobody outside can fake one to get a laptop revoked. Canary keys and ids never appear in the public KRL, log or ca.pub. The signed event is an integrity_alert with kind: canary_tripped, the canary id in indicator_ids and no key material; a revocation is a device_revoked with actor canary_tripped.

Revocation timing

Revocation takes effect at the device's next request. The server reads the revocation state on every challenge and again when it issues a certificate.

It does not recall certificates already issued. OpenSSH does not ask the CA whether a certificate is still good, so a certificate stays valid until it expires. That is at most cert_ttl after it was issued, and the reason the default is 10 minutes. dp-ssh-agent keeps a certificate in memory and reuses it while it has more than 60 seconds left.

The same timing applies when a device stops passing posture, or when the user revokes the CA's grant with dp grants revoke: the next certificate is refused; the current one runs out.

Two more things outlive a revocation:

If you need to cut someone off sooner, end their sessions on the servers and use OpenSSH's own revocation list (RevokedKeys in sshd_config, built with ssh-keygen -k). You can revoke by certificate serial (from dpass-ca certs list) or by the device's public key, which is the ssh_pubkey column of the devices table in the database. This is plain OpenSSH; dpass-ca does not build the list for you.

Logs

dpass-ca writes one line per event to stderr, as key=value pairs:

dpass-ca: event=issued serial=7 device=Xy.. key_id=dp:Xy..:alice@example.com principals=alice valid_before=1800000600 results=disk_encrypted/true/agent-reported,...
dpass-ca: event=denied error=denied reason="..." failed=disk_encrypted
dpass-ca: event=device_revoked device=Xy.. email=alice@example.com

Events include issued, denied, declined_unauthenticated, challenge_refused, device_revoked, person_revoked and error. Logs show predicate outcomes only. The CA never receives raw device facts.

A declined_unauthenticated line is an unsigned "no" from whoever posted it. It changes nothing on the CA and does not use up the challenge.

Backups

Back up three things:

What Path (from the config) If you lose it
SSH CA key ssh_ca_key Generate a new one and replace TrustedUserCAKeys on every server.
Audience key audience_key Every grant names the old key. Every person must run dp enroll again.
Database database All registrations, grants and revocations are gone. Everyone must enroll again.

Also keep the config file and the OAuth client secret.

The key files are secrets. Store backups encrypted, with the same care as the live files.

The database runs in WAL mode, so a plain copy of the main file can miss recent writes. Use SQLite's online backup while the CA runs:

sqlite3 /var/lib/dpass-ca/ca.sqlite ".backup '/backup/ca-$(date +%F).sqlite'"

Or stop serve and copy the file together with any -wal and -shm files beside it.

Restoring an old database undoes later revocations. A device or person revoked after the backup was taken is live again. After a restore, run the revocations again. Check dpass-ca devices list and dpass-ca people list against your records.

Running it