Buy

TKey ssh-agent

Description

The ssh-agent for TKey can be used for SSH Public Key Authentication, which is a more secure and cryptographically stronger method to authenticate against SSH servers compared to using passwords.

When the device app is loaded and running on the TKey, the status LED will indicate this with a blue color. When a signature is required it is indicated with a green flashing LED. Touch the TKey’s touch sensor to confirm the creation of a signature.

Cryptography

The algorithm used by the signer is Ed25519. The Ed25519 keypair is generated automatically on the TKey but under some user control (see USS below). The public key can be exported, but the private key will never leave the TKey.

The USS (User supplied secret) is an input the user specifies. This is one out of three parts that are used in the key derivation. Meaning a different USS gives a different identity, and hence a different keypair for the SSH agent. Giving the possibility to use multiple SSH identities on one TKey. Note: to remember the USS you are using, or you won’t be able to use that identity anymore.

Note: It is recommended to have a second way to authenticate, if for example you would lose your TKey, to not be completely locked out.

Below you will learn how to install tkey-ssh-agent and generate a public SSH key.

Installation and usage

Linux

Installing tkey-ssh-agent

We provide multiple types of packages for Linux, such as Debian, RPM, Arch, and Alpine. These are available for both amd64 and arm64. The app is statically linked.

If you need a different package or architecture, it is always an alternative to compile and install directly from source code. You will find the source code at our GitHub repository.

Below instructions are for a Debian package for amd64, but can be applied for each of these packages:

  • tkey-ssh-agent_1.0.0_linux_amd64.deb
  • tkey-ssh-agent_1.0.0_linux_arm64.deb
  • tkey-ssh-agent_1.0.0_linux_amd64.apk
  • tkey-ssh-agent_1.0.0_linux_arm64.apk
  • tkey-ssh-agent_1.0.0_linux_amd64.rpm
  • tkey-ssh-agent_1.0.0_linux_arm64.rpm
  • tkey-ssh-agent_1.0.0_linux_amd64.pkg.tar.zst
  • tkey-ssh-agent_1.0.0_linux_arm64.pkg.tar.zst

Note: the Alpine packages does not include a service compatible with OpenRC, and has to be added manually. For inspiration see the service used in systemd here.

  1. Check if tkey-ssh-agent is packaged for your distribution with the normal tools you use for installing software. If so, skip the rest of this list.
  2. Open a terminal and download the package, for example the Debian amd64 version. Change the link to the appropriate package for your system
    wget https://github.com/tillitis/tkey-ssh-agent/releases/download/v1.0.0/tkey-ssh-agent_1.0.0_linux_amd64.deb
  3. Install tkey-ssh-agent by using the command appropriate for your package manager. For example
    dpkg -i tkey-ssh-agent_1.0.0_linux_amd64.deb
apk add --allow-untrusted tkey-ssh-agent_1.0.0_linux_amd64.apk
rpm -ivh tkey-ssh-agent_1.0.0_linux_amd64.rpm
pacman -U tkey-ssh-agent_1.0.0_linux_amd64.pkg.tar.zst
  4. Note well: The packages depends on a pinentry program, typically pinentry-gnome3. You will need a pinentry program to open a window to input the User Supplied Secret. If you’re not running a major desktop like GNOME or KDE you have to make sure that your pinentry works and opens a graphical window. You can configure which pinentry program to run either by setting it in your ~/.gnupg/gpg-agent.conf or by adding a –pinentry flag to the systemd service.

Generating a public SSH key

  1. Insert your TKey in your device.
  2. Enable and start the systemd user service from your terminal.
    systemctl --user enable --now tkey-ssh-agent
  3. Make the SSH_AUTH_SOCK environment variable point to tkey-ssh-agent.
    export SSH_AUTH_SOCK=$XDG_RUNTIME_DIR/tkey-ssh-agent/sock
  4. Verify SSH_AUTH_SOCK is similar to: /run/user/999/tkey-ssh-agent/sock.
    echo $SSH_AUTH_SOCK

    Learn how to set the environment variable persistently, or use specific SSH agent configuration furthest down on the page.

  5. List your TKey’s public SSH key. This loads the required TKey device app, if not already loaded, and prompts you to input a User-Supplied Secret. The status indicator on your TKey shall become blue.
    ssh-add -L
  6. Go to tillitis.se/download and, in the table, click the application or protocol for which you want to use tkey-ssh-agent and follow the instructions. These are just examples, tkey-ssh-agent should work on any SSH enabled server that supports public key authentication.

For more information and configuration examples for SSH, see the manual page.

man tkey-ssh-agent

 

macOS

Installing tkey-ssh-agent

We distribute our officially supported tkey-ssh-agent package for MacOS through Homebrew so make sure to have Homebrew installed before proceeding.

  1. Open a terminal in MacOS. You will enter all the commands in the terminal.
  2. Install tkey-ssh-agent.
    brew install tkey-ssh-agent

Generating a public SSH key

  1. Insert your TKey in your device.
  2. Enable and start the system service from your terminal.
    brew services restart tkey-ssh-agent
  3. Make the SSH_AUTH_SOCK environment variable point to tkey-ssh-agent.
    export SSH_AUTH_SOCK="$HOMEBREW_PREFIX/var/run/tkey-ssh-agent.sock"
  4. Verify SSH_AUTH_SOCK is similar to: opt/homebrew/var/run/tkey-ssh-agent.sock.
    echo $SSH_AUTH_SOCK

    Learn how to set the environment variable persistently, or use specific SSH agent configuration furthest down on the page.

  5. List your TKey’s public SSH key. This loads the required TKey device app, if not already loaded, and prompts you to input a User-Supplied Secret. The status indicator on your TKey shall become blue.
    ssh-add -L
  6. Go to tillitis.se/download and, in the table, click the application or protocol for which you want to use tkey-ssh-agent and follow the instructions. These are just examples, tkey-ssh-agent should work on any SSH enabled server that supports public key authentication.

For more information and configuration examples for SSH, see the manual page.

man tkey-ssh-agent

Windows

Installing tkey-ssh-agent

We distribute our officially supported tkey-ssh-agent package for Windows through Winget so make sure to have Winget and PowerShell installed before proceeding.

If you prefer not to use PowerShell and Winget, you may download the tkey-ssh-agent msi package from our GitHub repository, install it, and then proceed to the heading Generating a public SSH key.

  1. Open PowerShell in Windows. You will enter all the commands in PowerShell.
  2. Install tkey-ssh-agent.
    winget install tkey-ssh-agent
  3. Install Gpg4win.
    (By default, TKey SSH Agent uses a pinentry tool from Gpg4win for requesting a User-Supplied Secret.)

    winget install gpg4win

Generating a public SSH key

  1. Insert your TKey in your device.
  2. Start TKey SSH Agent from the Windows Start menu. This shortcut launches tkey-ssh-agent-tray which runs tkey-ssh-agent with flags that set our default pipe name (which is needed later), and enables entering of a User-Supplied Secret.To make tkey-ssh-agent run automatically on startup, you can copy its shortcut to your “Startup” folder, as described in this article.
  3. Make the SSH_AUTH_SOCK environment variable point to tkey-ssh-agent.
    $env:SSH_AUTH_SOCK = '\\.\pipe\tkey-ssh-agent'

    SSH commands run in this PowerShell instance inherit the environment variable and connect to tkey-ssh-agent for operations. As will other commands such as git and code (Visual Studio Code) that run SSH.

    Learn how to set the environment variable persistently, or use specific SSH agent configuration furthest down on the page.

  4. List your TKey’s public SSH key. This loads the required TKey device app, if not already loaded, and prompts you to input a User-Supplied Secret. The status indicator on your TKey shall become blue.
    ssh-add -L
  5. If you are using Git, you can install Git-for-Windows which is commonly used together with SSH agents and Visual Studio Code.
    winget install git.git
  6. From the Windows Start menu, go to “Settings → Apps & features → Optional features” and add the “OpenSSH Client” feature.Note: The use of SSH requires that the OpenSSH Client feature is enabled and the commands ssh and ssh-add are available in PowerShell.
  7. If you want Git-for-Windows to use Windows OpenSSH Client instead of the default bundled SSH client, change the configuration.
    $sshpath = (get-command ssh.exe).path -replace '\\','/'
git config --global core.sshCommand $sshpath
git config --global --get core.sshCommand
  8. Verify the command output is simlar to C:/Windows/System32/OpenSSH/ssh.exe.
  9. Go to tillitis.se/download and, in the table, click the application or protocol for which you want to use tkey-ssh-agent and follow the instructions. These are just examples, tkey-ssh-agent should work on any SSH enabled server that supports public key authentication.

The SSH_AUTH_SOCK environmental variable and SSH config

To make ssh, ssh-add and other tools find and use tkey-ssh-agent you have two options

  1. Set the environment variable, SSH_AUTH_SOCK, persistently, or
  2. Configure SSH to specify which IdentityAgent to use

If you are to use more than one SSH agent, option 2 are recommended.

1. Set the environment variable, SSH_AUTH_SOCK, persistently

To set the SSH_AUTH_SOCK environment variable persistently, so different SSH tools can find and communicate with the SSH agent, add this line to your startup file, .bashrc, .zshrc or equivalent

For Linux use

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

For macOS use

export SSH_AUTH_SOCK="$HOMEBREW_PREFIX/var/run/tkey-ssh-agent.sock"

For Windows run this command in PowerShell as administrator to set it persistently (see this article for more info)

[Environment]::SetEnvironmentVariable('SSH_AUTH_SOCK', '\\.\pipe\tkey-ssh-agent', 'Machine')

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

ssh-add -L

 

2. Configure SSH to specify which IdentityAgent to use

tkey-ssh-agent does not have a configuration file, but you can configure a specific SSH agent (“IdentityAgent”) to use depending on the host you want to access. This option overrides the SSH_AUTH_SOCK environment variable.

Add the following to ~/.ssh/config (if the file does not exist, create it) to make it use tkey-ssh-agent when connecting to “example.com”:

For Linux

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

Above is valid for macOS and Windows as well, but use the appropriate path in IdentityAgent

macOS: ${HOMEBREW_PREFIX}/var/run/tkey-ssh-agent.sock
Windows: \\.\pipe\tkey-ssh-agent

Another example is to 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

Again, this is valid for macOS and Windows, but use the appropriate path in IdentityAgent.

When using this approach, the simplest way of accessing the public key is to use

tkey-ssh-agent -p --uss