alias
Keycutter

Keycutter: FIDO SSH keys made easy.

Keycutter simplifies using multiple private SSH keys on multiple devices.

Ever wondered how to contribute to an open-source project on GitHub from an employer managed (i.e. untrusted) laptop, without compromising the security of your personal GitHub account?

Keycutter came out of an attempt to solve this problem but evolved into a tool to improve security by simplifying management and use of FIDO SSH Keys.

Keycutter consists of:

• keycutter: A CLI tool for creating FIDO SSH keys and managing SSH config.
• SSH Keytags: A naming convention that removes need for custom SSH configuration.
• SSH configuration and scripts: These don't require modification to use.

It supports:

• Multi-account SSH access to services: GitHub.com, GitLab.com, etc.
• FIDO SSH keys ( e.g. Yubikey )): Uncopiable, physical presence verification, pin retry lockout.
• Selective SSH Agent Forwarding: Enforce security boundaries.
• Public SSH Key privacy: Only offer relevant keys to remote host.
• SSH over SSM (AWS): Public key removed from remote host after login.
• WSL: Windows Subsystem for Linux
• VSCode: Connect via Remote-SSH Extension

While initially created for use with YubiKeys and GitHub, Keycutter supports other devices and services.

Contents

• Quickstart
• SSH Keytags
• Installation
• Usage
• ISSUES

Quickstart

curl https://raw.githubusercontent.com/bash-my-aws/keycutter/master/install.sh | bash

Goals

• Safe: Don't screw up users SSH keys or config. Confirm and backup changes.
• Simple: Keep the code and config it generates simple to audit.
• Solid: Support all the things people use SSH for (e.g. scp, rsync, etc).

SSH Keytags

Managing multiple FIDO SSH keys across multiple devices and services can be an effort.

Keycutter introduces SSH Keytags, labels to help you organise and keep track of your FIDO SSH Keys across multiple devices and services.

SSH Keytags are used:

• In the SSH Key filename
• In the public key comment
• In the key name on services like GitHub

SSH Keytag format: <service>_<identity>@<device>

• Service: FQDN of remote service (e.g. gitlab.com)
• Identity: The user account on remote service (e.g. alex-work)
• Device: The hardware security key or computer where the private key resides.

Read more about SSH Keytags

Installation

1. Install Prerequisites

Note: The installer checks requirements for you.

Required:

• Bash >= 4.0
• Git >= 2.34.0
• OpenSSH >= 8.2p1 (WSL users need ssh-sk-helper(OpenSSH for Windows >= 8.9p1-1))
• nc

Recommended:

• GitHub CLI >= 2.0: (Greater than 2.4.0+dfsg1-2 on Ubuntu)
• YubiKey Touch Detector: Get notified when YubiKey needs a touch.
• YubiKey Manager (ykman): Used to set a PIN on Yubikeys, and perform other configuration.

2. Install Keycutter

Clone the Git repo and run installer:

git clone https://github.com/bash-my-aws/keycutter
cd keycutter
./install.sh

WSL users: Add this to you shell to your shell profile (e.g. bashrc or zshrc):

# WSL (Windows Subsystem for Linux) users need to set the path to ssh-sk-helper.exe
if [[ -f "/mnt/c/Program Files/OpenSSH/ssh-sk-helper.exe" ]]; then
	export SSH_SK_HELPER="/mnt/c/Program Files/OpenSSH/ssh-sk-helper.exe"
fi

Usage

Create a FIDO SSH Key

Provide an SSH Keytag (<service>_<identity>@<device>) to the create command:

keycutter create github.com_alex@workpc

For a particular service and identity on a device:

• Separate the domain name and user name with an underscore.
• Append the device name after the @ symbol.

Using the keys

1. Clone a GitHub repo using your new key

git clone [email protected]_alex:bash-my-aws/keycutter

2. Commit a change signed with your new SSH Key

cd keycutter
date >> README.md 
git commit -m "I signed this commit with my new SSH Key"

3. Explore your new config

You're ready for FIDO SSH access to anything you were using file based SSH keys for.

Example ssh config generated by keycutter

With the exception of a single Include line added to ~/.ssh/config, all SSH configuration generated by keycutter lives under ~/.ssh/keycutter.

$ tree ~/.ssh

/home/alex/.ssh
├── config
├── config.backup.1728393975
└── keycutter
    ├── agents
    ├── hosts
    ├── keycutter.conf
    ├── keys
    │   ├── github.com_alexpersonal@x2
    │   ├── [email protected]
    │   ├── github.com_alexwork@x2
    │   ├── [email protected]
    │   ├── ssh.github.com_alex-personal@x2 -> github.com_alexpersonal@x2
    │   └── ssh.github.com_work-user@x2 -> github.com_alexwork@x2
    └── scripts
        ├── ssh-agent-ensure
        ├── ssh.bat
        ├── ssh-ssm
        ├── ssh-vanilla
        └── sync-file-to-remote

Updating Keycutter

It's recommended to update keycutter periodically to ensure you have the latest features and bug fixes.

To update an existing installation of Keycutter, use the following command:

keycutter update

This command will:

1. Pull the latest changes from the Keycutter git repository.
2. Check and update any requirements.
3. Update your SSH configuration with any new changes.

Here's an example of what you might see when running the update command:

🔄 Updating Keycutter from git...
Confirm user presence for key ECDSA-SK SHA256:bW8s2icYERtlbt9Y9jrzCDEcdgcmMbWRiBjxtroNLoI
User presence confirmed
Keycutter is already up to date.
All requirements are met.
Keycutter SSH update complete.

See also

• Keycutter Documentation

• Tips and tricks: Undocumented features and cool tricks.

• Prior art (and inspiration):

  • ssh-over-ssm (github.com): Original source of keycutter/scripts/ssh-ssm.
  • ssh-ident (github.com): Different agents and different keys for different projects, with ssh.