Buy

Guide: migrating to new version of tkey-ssh-agent

Introduction

This is a guide to migrate to a newer version of tkey-ssh-agent. This is only applicable for major releases where the generated identity has changed, i.e., when the embedded device application, tkey-device-signer, has been updated.

When a new identity is generated the public key on all the services/servers where you use TKey must be updated.

In general this can be split in two categorize. Updating your public key where:
1) you have an alternative method of authentication; or
2) you first need to authenticate with your TKey, in order to update the public key.

For category 1, where you have an alternative method of authentication, you can skip this guide. This goes for services like GitHub, GitLab and so on, where you usually sign in into their web interface to register keys for authentication. For these types of services you can install the new version, retrieve you new public key, and then refer to their documentation on how to register a new key.

The same goes for servers where you have an alternative way of authenticating. Don’t forget to remove the old key.

For category 2, servers or other services where you might want or need to use the same TKey in order to first authenticate and then update the authentication key.

This method tries to simplify the update process by removing the issue of having two versions of the same application installed simultaneously. This method is possible to use as long as the the device application of the newer version is compatible with currently installed tkey-ssh-agent.

For this method you have to to download and install tkey-runapp, a client application that simply loads a device applications onto the TKey. Follow the steps below.

Steps

  1. Download and install tkey-runapp from https://github.com/tillitis/tkey-devtools/releases
  2. Download the new version of tkey-device-signer from https://github.com/tillitis/tkey-device-signer/releases
  3. Open a terminal and run: tkey-runapp signer.bin-vX.Y.Z --uss
  4. Enter the USS you ordinary use. You can run without –uss but we highly recommend you use USS.

    Run tkey-runapp -h for more options.

    Now you can use your already installed tkey-ssh-agent with the new tkey-device-signer you just loaded
     
  5. Run ssh-add -L to retrieve your new public key. This requires that you have the environment variable, SSH_AUTH_SOCK, set to point at the tkey-ssh-agent socket. If not, you can also use tkey-ssh-agent -p.

    Copy and save the public key for later.
     
  6. Unplug and reinsert your TKey.

    Now it is time to authenticate with the servers you need to update you identity on.
     
  7. Use your TKey, as you normally would, to authenticate to the server.
  8. Update .ssh/authorized_keys (or other appropriate location) by adding the new public key you saved in step #4.

    Don’t remove the previously used public key yet. First we want to make sure the new key is registered properly and the authentication works.
     
  9. Unplug and reinsert you TKey again.
  10. Run tkey-runapp signer.bin-vX.Y.Z --uss then enter the USS used in step #3.
  11. Try to authenticate with the same server again, now using the new keys.

    If the authentication is successful you can remove the previously used public key from .ssh/authorized_keys.
     
  12. Once you have updated all your servers, you are ready to update tkey-ssh-agent.
    Find the instructions at https://tillitis.se/app/tkey-ssh-agent.
    You can now remove tkey-runapp and signer-vX.Y.Z.bin from your computer.

FAQ

  1. Is my old identity lost?
    • Your identity previously used identity is not lost. You can always install an older version and use it to authenticate, if you for example forgot to update a service.