NAME

       tkey-ssh-agent — An SSH agent backed by Tillitis TKey

SYNOPSIS

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

DESCRIPTION

       tkey-ssh-agent is an alternative SSH agent backed by an Ed25519 signer device-app which it uploads to the
       Tillitis TKey, a small computer in the form of a USB stick.

       It  works  as  an  OpenSSH-compatible  agent  for  all SSH programs, supporting a necessary subset of the
       OpenSSH agent protocol. You can use it to login to other systems or to sign  Git  commits,  for  example.
       Your ephemeral private key never leaves the TKey.

       The  act of uploading the signer app, with an optional User Supplied Secret, creates a new unique, stable
       but ephemeral identity for that specific combination of TKey, signer app binary, and USS.

       The options are as follows:

       -L | --list-ports
               List possible serial ports to use with --port and exit.

       -a | --agent-path path
               Bind the agent to the Unix-domain socket at path.

       --help  Output help text and exit.

       -p | --show-pubkey
               Extract the ssh-ed25519 public key from the TKey and exit.

       --pinentry command
               Specify pinentry command for use by --uss.   The  default  is  found  by  looking  in  your  gpg-
               agent.conf for pinentry-program. If this is not found, the pinentry(1) command is used.

       --port path
               Set serial port device path. If this is not set, auto-detection will be attempted.

       --speed bit_speed
               Set serial port speed in bits per second. Default is 62500 b/s.

       --uss   Interactively  ask  for a secret to be hashed as the User Supplied Secret. The USS is loaded onto
               the TKey along with the signer. A different USS results in a different pair of SSH public/private
               keys.

       --uss-file path
               Read a secret from a file path and hash 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).

       --version
               Output version information.

   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  new  identity. The USS is input interactively using a pinentry(1) command, see the
       --uss option for more information. If not run with --uss, the TKey/signer combination will have a  single
       identity.

   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

ENVIRONMENT

       To  make ssh(1), ssh-add(1) and other tools use tkey-ssh-agent you must set the SSH_AUTH_SOCK environment
       variable for them, so they can find and communicate with the SSH agent. 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. This would make all
       tools that honour SSH_AUTH_SOCK use tkey-ssh-agent.

       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.

       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

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

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.

AUTHORS

       Tillitis AB, https://tillitis.se/

CAVEATS

       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
       is not already running on the TKey it is 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 let other
       client apps also be able to speak to it.

Debian                                             $Mdocdate$                                  tkey-ssh-agent(1)