Skip to content

Latest commit

 

History

History
68 lines (44 loc) · 3.33 KB

yubikey.md

File metadata and controls

68 lines (44 loc) · 3.33 KB
Raw

Configuring and Using the Yubikey

Table of Contents

[TOC]

The following setup enables us to use the YubiKey with OpenPGP, the Authentication subkey as an SSH key and the Encryption subkey to sign Git commits.

⚠️

Consider setting up 2 Yubikeys. Keys will fail, so having a backup reduces the pain and grief when failures occur.

The Tooling

You'll be using the following tooling:

Setup Instructions

WARNING: When setting a pin, make sure it is between 6 and 8 ASCII characters, longer pins may be silently truncated.

  1. Follow the instructions for installing yubikey-agent. But do not run the setup command for your yubikey. This is handled as part of the yubikey-reset.sh script below.

    • Don't forget to add export SSH_AUTH_SOCK="$(brew --prefix)/var/run/yubikey-agent.sock" to your ~/.zshrc and restart the shell.

  2. Follow the instructions for installing ykman

  3. Follow the instructions below for setting a "cached" touch policy. These steps, and the script run, will create keys and certificates using ykman.

  4. Set up Git commit signing using the YubiKey's SSH key:

    1. Export the YubiKey's public key to the file system

      ssh-add -L | grep YubiKey >~/.ssh/id_ecdsa_yubikey.pub

    2. Configure Git to use your SSH key for signing, referencing the file created above.

    3. Add the SSH key to your GitLab profile:

  5. Enable 2FA with the Yubikey for your favorite services, e.g.:

    • GitLab
    • Okta
    • AWS
    • Google

Setting a "cached" touch policy

When following the below instructions, your Yubikey will be reset

When doing a rebase with multiple commits, or using ssh automation like knife ssh ... it will be painful using the default yubikey-agent configuration since a touch is required for every signature or ssh session. This is default configuration but we set a touch policy of "cached" with the following script, this will cache touches for 15 seconds:

  1. Validate ykman has access to the key, you may need to re-insert your yubikey, run ykman info to confirm.
  2. Run the scripts/yubikey-reset.sh script, PIN=<your pin> scripts/reset-yubikey.sh, this will invalidate the previous key and set a new one:

Workaround if your yubikey is not responding

If you discover that your Yubikey is not responding, a restart of the yubikey-agent may be needed. Usually ssh-add -l will throw an error.

Run the following brew command on your local machine.

brew services restart yubikey-agent

We suspect that this is impacting only Macbook / macOS users.