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 an officially supported tkey-ssh-agent deb package for the Ubuntu distribution. If you run another Linux distribution, you may download the tkey-ssh-agent source code from our GitHub repository, compile and install, and then proceed to the heading Generating a public SSH key.

  1. Open a terminal in Ubuntu. You will enter all the commands in the terminal.
  2. Download tkey-ssh-agent.
    wget https://github.com/tillitis/tkey-ssh-agent/releases/download/v0.0.6/tkey-ssh-agent_0.0.6-1_amd64.deb
    
  3. Install tkey-ssh-agent.
    sudo dpkg -i tkey-ssh-agent_0.0.6-1_amd64.deb
    

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