tkey-ssh-agent(1)

📦
version 1.1.1 · 2 versions
, in alpine 3.24, ubuntu stonking

💖 tkey-ssh-agent — the manual page, but make it slay ✨

okay bestie, grab your boba because we're reading the General Commands Manual entry for tkey-ssh-agent(1) and it's genuinely such a cool little program 🫶

🎀 NAME 🎀

tkey-ssh-agent — an SSH agent that's backed by a Tillitis TKey 💅

🌸 SYNOPSIS 🌸

tkey-ssh-agent [-L | --list-ports] [-a | --agent-path path]
               [--force-full-uss] [--help] [-p | --show-pubkey]
               [--pinentry command] [--port path] [--speed bit_speed]
               [--uss] [--uss-file path] [--version]

✨ DESCRIPTION ✨

so tkey-ssh-agent is an alternative SSH agent, and it's backed by an Ed25519 signer device-app that it uploads straight onto the Tillitis TKey — which is literally a whole tiny computer shaped like a USB stick 🌈 iconic honestly.

It works as an OpenSSH-compatible agent for all your SSH programs, supporting the necessary subset of the OpenSSH agent protocol. You can use it to log in to other systems, or to sign Git commits, for example 🧚 and the best part? Your ephemeral private key never leaves the TKey. periodt. 💅

The act of uploading the signer app — with an optional User Supplied Secret — creates a brand new unique, stable but ephemeral identity for that exact combination of TKey, signer app binary, and USS. it's giving bespoke key material 🔥

The options are as follows, bestie, and yes we're doing all of them:

👑 OPTIONS 👑

  • -L, --list-ports — shows you all the possible serial ports you could use with --port, then dips out and exits 📋
  • -a, --agent-path path — binds the agent to the Unix-domain socket at path 🔌
  • --help — spits out the help text and exits, the classic 🫶
  • -p, --show-pubkey — extracts the ssh-ed25519 public key from the TKey and exits 🔑
  • --pinentry command — tells it which pinentry command to use for --uss. The default gets found by peeking in your gpg-agent.conf for pinentry-program, and if that's not there, the pinentry(1) command gets used ngl 💬
  • --port path — sets the serial port device path. If you don't set it, it's gonna try auto-detection, no cap 🎧
  • --speed bit_speed — sets the serial port speed in bits per second. Default is 62500 b/s 🏎️
  • --uss — interactively asks for a secret to be hashed as the User Supplied Secret. The USS gets loaded onto the TKey right along with the signer. Different USS → different pair of SSH public/private keys 💖
  • --uss-file path — reads a secret from a file at path and hashes its contents as the User Supplied Secret to be mixed into the TKey identity. Use '-' (dash) to read from stdin. The full contents are hashed unmodified — i.e. newlines are not stripped, okay? don't @ me 🙈
  • --force-full-uss — forces the use of a full 32 byte USS digest. For backwards compatibility the default is 31 bytes. Use only with --uss or --uss-file ⚠️
  • --version — outputs version information, slay 🎀

🔐 User Supplied Secret 🔐

You are encouraged to run tkey-ssh-agent with --uss, meaning that when the signer app is loaded onto the TKey, a User Supplied Secret (USS) is loaded as well. In short: changing the USS results in a different SSH ed25519 key — a whole new identity, like a glow-up but for cryptography 💅 The USS is input interactively using a pinentry(1) command, peep the --uss option for more info. And if you don't run it with --uss, the TKey/signer combo just has a single identity. simple as 🦋

🖥️ systemd-based systems 🖥️

With the source code we provide a systemd unit file that can be used to automatically start the tkey-ssh-agent when a user logs in. If this unit file is installed (for instance with a package for your operating system) you can run the following — as your own user — to start the agent right now and enable it for future logins:

$ systemctl --user enable --now tkey-ssh-agent

look at that, one command, zero stress, main character energy 😌✨

🌈 ENVIRONMENT 🌈

To make ssh(1), ssh-add(1) and other tools actually use tkey-ssh-agent, you've gotta set the SSH_AUTH_SOCK environment variable for them, so they can find the SSH agent and talk to it. For your current shell this can be done like this (bash/zsh):

export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/tkey-ssh-agent/sock"

This line can also be added to the startup file for your shell, e.g. in .bashrc. That would make all tools that honour SSH_AUTH_SOCK use tkey-ssh-agent. set it and forget it bestie 💜

With SSH_AUTH_SOCK correctly set you can see the current SSH ed25519 public key by running:

$ ssh-add -L

📁 FILES 📁

tkey-ssh-agent does not have a configuration file. no conf, no fuss, we love a low-maintenance king 🙌

You might, however, want to configure ssh(1) to use a specific SSH agent ("IdentityAgent") depending on the host you want to access. Add the following to ~/.ssh/config to make it use tkey-ssh-agent when connecting to "example.com":

  Host example.com
    IdentityAgent ${XDG_RUNTIME_DIR}/tkey-ssh-agent/sock

Or use tkey-ssh-agent for all hosts except "example.com":

  Host example.com
    IdentityAgent $SSH_AUTH_SOCK

  Host *
    IdentityAgent ${XDG_RUNTIME_DIR}/tkey-ssh-agent/sock

choose your own adventure, literally 🦋

🍓 EXAMPLES 🍓

Running manually against a TKey with automatic port detection and interatively ask for the User Supplied Secret:

$ tkey-ssh-agent -a ./agent.sock --uss

Running manually against qemu (look when qemu is starting what device it uses) and interactively ask for the User Supplied Secret:

$ tkey-ssh-agent -a ./agent.sock --port /dev/pts/1 --uss

Ask the agent about the TKey public key:

$ SSH_AUTH_SOCK=./agent.sock ssh-add -L

Login to localhost using the agent (copy the public key to ~/.ssh/authorized_key first):

$ SSH_AUTH_SOCK=./agent.sock ssh -F /dev/null localhost

okay go off, that last one is lowkey so satisfying when it works 😭🔥

👀 SEE ALSO 👀

ssh(1) ssh-add(1) ssh-agent(1)

📜 STANDARDS 📜

tkey-ssh-agent attempts to follow a subset of the OpenSSH Agent protocol. It doesn't do anything on calls to add/remove keys, or to lock/unlock it with a passphrase. it's just not that kind of agent, and that's fine 💁♀️

💜 AUTHORS 💜

Tillitis AB, https://tillitis.se/

⚠️ CAVEATS ⚠️

read this part, bestie, it explains a thing that surprises people fr fr

The tkey-ssh-agent only connects to the TKey when an SSH agent operation is requested (e.g. when you attempt to log in somewhere or request the public key) and disconnects soon afterwards. If the signer app isn't already running on the TKey, it's first uploaded to the TKey and started.

This means that it will only ask for the User Supplied Secret (if started using the --uss flag) when the agent is actually requested to do something for the first time — not when the TKey is inserted, as the user perhaps expected 😭 The reason is that the tkey-ssh-agent shouldn't hog the device and should let other client apps also be able to speak to it. sharing is caring 🫶

and that's the whole page, bestie!! 🎀🌸 this one came from Debian, dated $Mdocdate$, and it lives in section tkey-ssh-agent(1) of the manual — ty for reading, ily, go touch grass now 💖✨

📦 where this page comes from