SSH with security keys

This tutorial covers how to connect to a VM using OpenSSH with security keys on Compute Engine.

Note: To use this feature both the client and VM must support OpenSSH 8.2 or later. On Compute Engine, OpenSSH 8.2 is currently supported on VMs running Ubuntu 20.04 LTS.

With the release of the FIDO2/U2F feature in OpenSSH 8.2, you can now enable hardware-backed SSH key pairs using security keys. Security keys provide a higher level of security that can help reduce the impact of attacks.

Overview

To generate SSH keys that are linked to security keys, use the ssh-keygen command with the -t ecdsa-sk flag. This command creates a public key, private key, and a U2F key handle (or FIDO2 credential ID). These items are stored as follows:

• The private key is stored on the security device.
• The key handle and public key are stored locally in the traditional SSH key files. The key handle can be optionally encrypted with a passphrase.

After the SSH key is generated, configure your user account to use the generated SSH public key.

Finally, you can SSH to the VM. If the VM accepts one of your ecdsa-sk keys, your client prompts you to touch your security key to verify the connection.

Objectives

This tutorial shows how to complete the following steps:

1. Create a VM. On Compute Engine, Ubuntu 20.04 contains the latest OpenSSH 8.2 installation which can be used to verify a security key. This tutorial uses a VM that runs on Ubuntu 20.04.
2. On a client, install OpenSSH 8.2 and generate SSH public keys. This tutorial uses a client that runs on Ubuntu 16.04.
3. Add the generated SSH public key to the VM.
4. Connect to the VM from the client by using OpenSSH with security keys.

Costs

This tutorial uses billable components of Google Cloud including Compute Engine.

You can estimate your daily or monthly costs by using the pricing calculator.

New Google Cloud users might be eligible for a free trial.

Before you begin

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. In the Cloud Console, on the project selector page, select or create a Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to the project selector page

3. Make sure that billing is enabled for your Google Cloud project. Learn how to confirm billing is enabled for your project.

4. Learn how to use Cloud Shell to run gcloud command-line tool commands.
5. On your client, install or update to the latest version of the gcloud command-line tool.
6. Optional: Set a default region and zone.

Set up the VM

1. In the Google Cloud Console, go to Cloud Shell.

   Go to Cloud Shell

2. Export an environment variable to set your project ID for future commands:

   export PROJECT_ID='PROJECT_ID'

3. Create a VM host-vm in the zone us-west4-c using the latest Ubuntu 20.04 LTS image. Also enable OS Login on the VM. OS Login is used to manage access to the VM.

   Note: You can use any VM name or zone of your preference.

   To create this VM, run the following command:

   gcloud compute instances create host-vm \
      --project $PROJECT_ID \
      --zone us-west4-c \
      --image-family ubuntu-2004-lts \
      --image-project ubuntu-os-cloud \
      --metadata enable-oslogin=true
   

   Pro Tip:If you want other members of your team to access this VM, ensure that you grant these users the required access to the VM.

4. Generate keys for the VM. When you connect to a VM using the gcloud compute ssh command, Compute Engine automatically generates an RSA SSH key pair for the VM.

   gcloud compute ssh host-vm
   

Set up local workstation (client)

A local workstation or client is the device used to connect to the cloud network.

Note: For this tutorial, we use a Linux operating system as the local workstation.

1. On your local Linux workstation, install OpenSSH 8.2. Currently, the best option is to compile from source because OpenSSH 8.2 is not yet available for all Linux distributions.

   For example, on an Ubuntu 16.04 client you would complete the following steps:

   1. Install dependencies.

      sudo apt update
      sudo apt install build-essential

      sudo apt-add-repository ppa:yubico/stable

      sudo apt update
      sudo apt install libz-dev libcurl4-openssl-dev libssl-dev libcbor-dev libfido2-dev

   2. Setup a working directory.

      mkdir openssh-8
      cd openssh-8

   3. Download the Openssh 8.2 package.

      wget http://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-8.2p1.tar.gz
      tar xvzf openssh-8.2p1.tar.gz
      cd openssh-8.2p1
      

   4. Install OpenSSH 8.2 with security key support.

      ./configure --with-security-key-builtin

      make

      sudo make install

   5. Verify the install.

      ssh -V

      The output should resemble the following.

      OpenSSH_8.2p1, OpenSSL 1.0.2g  1 Mar 2016

   6. Run the ssh-keygen command with the -t ecdsa-sk flag.

      The output should resemble the following.

      Generating public/private ecdsa-sk key pair.
      You may need to touch your authenticator to authorize key generation.
      Key enrollment failed: device not found
      

2. Plug the key into the local workstation.

3. Run the ssh-keygen with the -t ecdsa-sk flag. In the following example, the generated SSH key pair is named my-sk-bound-ssh-key.

   ssh-keygen -t ecdsa-sk "my-sk-bound-ssh-key"

   The output should resemble the following.

   Generating public/private ecdsa-sk key pair.
   You may need to touch your authenticator to authorize key generation.Enter file in which to save the key (/home/$USER/.ssh/id_ecdsa_sk):
   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in /home/$USER/.ssh/id_ecdsa_sk
   Your public key has been saved in /home/$USER/.ssh/id_ecdsa_sk.pub
   The key fingerprint is:
   SHA256:esvq6KPZ5FGttkaYUUeUcf/Oo0hhsRAaB6NKN48kkeo ubuntu-17-02-2020-4432343
   The key's randomart image is:
   +-[ECDSA-SK 256]--+
   |  ..  ++*o.      |
   |  .. ..=oo .     |
   | .o =.... . .    |
   |.. =.+ . . o .   |
   |. . .+o S +   .  |
   | E  o..o . . o   |
   |    o.+ . .   +  |
   |   =.+.+ o . . . |
   |  oo=++.o . .    |
   +----[SHA256]-----+
   

4. On your local workstation, install or update to the latest version of the gcloud command-line tool.

5. Add the security key to the authorized file on the VM. OS Login is enabled on the host-vm, so you can use the gcloud compute os-login ssh-keys add command to associate the public SSH keys.

   gcloud compute os-login ssh-keys add \
       --project $PROJECT_ID \
       --key-file .home/$USER/.ssh/id_ecdsa_sk
   

   For more information, see Adding SSH keys to a user account.

   Note: If you had chosen not to enable OS Login when you created the host-vm, you can manually add the SSH keys. See Adding or removing project-wide public SSH keys.

6. You can now connect to the VM from a local workstation using OpenSSH with security keys.

   To connect, run the following command:

   gcloud compute ssh host-vm
   
   # Prompt for user to touch security key
   Confirm user presence for key ECDSA-SK SHA256:...
   Welcome to Ubuntu Focal Fossa...
   

   If your setup was successfully completed, when you SSH, you are prompted to authenticate access by touching the security key. The VM then verifies the key and grants access.

Cleaning up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this tutorial:

1. In the Google Cloud Console, go to Cloud Shell.

   Go to Cloud Shell

2. Delete the instance named host-vm:

   gcloud compute instances delete host-vm
      --project $PROJECT_ID \
      --zone us-west4-c

What's next

• Learn more about OS Login.

• Review other advanced methods for connecting to VMs on Compute Engine.

• Learn how to troubleshoot SSH issues.

• Learn more about securely connecting to VMs.