.Dd $Mdocdate$
.Dt tkey-ssh-agent 1
.Os
.Sh NAME
.Nm tkey-ssh-agent
.Nd An SSH agent backed by Tillitis TKey
.\" .Sh LIBRARY
.\" For sections 2, 3, and 9 only.
.Sh SYNOPSIS
.Nm
.Op Fl L | -list-ports
.Op Fl a | -agent-path Ar path
.Op Fl -help
.Op Fl p | -show-pubkey
.Op Fl -pinentry Ar command
.Op Fl -port Ar path
.Op Fl -speed Ar bit_speed
.Op Fl -uss
.Op Fl -uss-file Ar path
.Op Fl -version
.Sh DESCRIPTION
.Nm
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.
.Pp
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.
.Pp
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.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl L | -list-ports
List possible serial ports to use with
.Fl -port
and exit.
.It Fl a | -agent-path Ar path
Bind the agent to the
.Ux Ns -domain socket at path.
.It Fl -help
Output help text and exit.
.It Fl p | -show-pubkey
Extract the ssh-ed25519 public key from the TKey and exit.
.It Fl -pinentry Ar command
Specify pinentry command for use by
.Fl -uss .
The default is found by looking in your gpg-agent.conf for
pinentry-program. If this is not found, the
.Xr pinentry 1
command is used.
.It Fl -port Ar path
Set serial port device path. If this is not set, auto-detection will
be attempted.
.It Fl -speed Ar bit_speed
Set serial port speed in bits per second. Default is 62500 b/s.
.It Fl -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.
.It Fl -uss-file Ar 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).
.It Fl -version
Output version information.
.El
.Ss User Supplied Secret
.Pp
You are encouraged to run
.Nm
with
.Fl -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
.Xr pinentry 1
command, see the
.Fl -uss
option for more information. If not run with
.Fl -uss ,
the TKey/signer combination will have a single identity.
.Ss systemd-based systems
With the source code we provide a systemd unit file that can be used to
automatically start the
.Nm
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:
.Bd -literal
$ systemctl --user enable --now tkey-ssh-agent
.Ed
.\" .Sh CONTEXT
.\" For section 9 functions only.
.\" .Sh IMPLEMENTATION NOTES
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
To make
.Xr ssh 1 ,
.Xr ssh-add 1 and other tools use
.Nm
you must set the
.Sy 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):
.Bd -literal
export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/tkey-ssh-agent/sock"
.Ed
.Pp
This line can also be added to the startup file for your shell, e.g. in
.Sy .bashrc.
This would make all tools that honour
.Sy SSH_AUTH_SOCK
use
.Nm .
.Pp
With
.Sy SSH_AUTH_SOCK
correctly set you can see the current SSH ed25519 public key by
running:
.Bd -literal
$ ssh-add -L
.Ed
.Sh FILES
.Nm
does not have a configuration file.
.Pp
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
.Sy ~/.ssh/config
to make it use
.Nm
when connecting to "example.com":
.Bd -literal
  Host example.com
    IdentityAgent ${XDG_RUNTIME_DIR}/tkey-ssh-agent/sock
.Ed
.Pp
Or use
.Nm
for all hosts except "example.com":
.Bd -literal
  Host example.com
    IdentityAgent $SSH_AUTH_SOCK

  Host *
    IdentityAgent ${XDG_RUNTIME_DIR}/tkey-ssh-agent/sock
.Ed
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.Sh EXAMPLES
.Pp
Running manually against a TKey with automatic port detection and
interatively ask for the User Supplied Secret:
.Bd -literal
$ tkey-ssh-agent -a ./agent.sock --uss
.Ed
.Pp
Running manually against qemu (look when qemu is starting what device
it uses) and interactively ask for the User Supplied Secret:
.Bd -literal
$ tkey-ssh-agent -a ./agent.sock --port /dev/pts/1 --uss
.Ed
.Pp
Ask the agent about the TKey public key:
.Bd -literal
$ SSH_AUTH_SOCK=./agent.sock ssh-add -L
.Ed
.Pp
Login to
.Sy localhost
using the agent (copy the public key to ~/.ssh/authorized_key first):
.Bd -literal
$ SSH_AUTH_SOCK=./agent.sock ssh -F /dev/null localhost
.Ed
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.Sh SEE ALSO
.Xr ssh 1
.Xr ssh-add 1
.Xr ssh-agent 1
.Sh STANDARDS
.Nm
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.
.\" .Sh HISTORY
.Sh AUTHORS
Tillitis AB, https://tillitis.se/
.Sh CAVEATS
.Pp
The
.Nm
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.
.Pp
This means that it will only ask for the User Supplied Secret (if
started using the
.Fl -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
.Nm
shouldn't hog the device and let other client apps also be able to
speak to it.
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS