Quick start: enroll a device
This page is for a person who needs SSH access to a team's systems, whether
you are on that team or an outside collaborator. You need the URL of the
team's certificate server, for example
https://ssh-ca.example.com.
Nothing here lets your organization change your device. You choose which checks to share, and you can stop at any time.
1. Install
On Linux, install your distribution's package if your team gave you one (the
repository builds .deb, .rpm and Arch packages). Otherwise build from
source from a checkout of the Device Passport repository. Repository access is required for a source build.
cargo install --locked --path crates/dp-agent # dpassd
cargo install --locked --path crates/dp-cli # dp
cargo install --locked --path crates/dp-ssh-agent # dp-ssh-agent
2. Start the agent
sudo ~/.cargo/bin/dpassd init --owner-uid "$(id -u)"
sudo ~/.cargo/bin/dpassd run --allow-software-key
init creates the device keys and makes you the device's owner. With the
Linux package, run sudo dpassd init --owner-uid "$(id -u)" first, then
start the service with sudo systemctl enable --now dpassd.service.
Run the foreground agent in a separate terminal and leave it running during
setup. Release builds refuse the v0 software device key unless you pass
--allow-software-key.
See what your device would report before you share anything:
dp status
3. Set up
dp setup https://ssh-ca.example.com
This opens your browser to sign in with your work account. A consent page
then lists each check your organization wants to ask, in plain language,
and the hosts ssh will use the certificate for. One Allow covers both.
If your organization preset its server on this device, dp setup needs no
URL, and the tray shows "Set up Device Passport…" as its first item.
4. Use ssh as usual
Start the ssh-agent in your session (the Linux package has a systemd user unit for it):
dp-ssh-agent
ssh alice@build1.prod.example.com
If a check fails, the certificate server says which one, and dp why
shows the fix:
dp why
Stay in control
dp grants # what each organization may ask
dp grants revoke <grant_id> # stop answering an organization, at once
dp log # every question asked and how it was answered
dp log verify # check the log's hash chain
Next
- Your organization requires a token key: Hardware keys.
- What your answers prove, and what your organization can and cannot learn: Threat model.