This content originally appeared on DEV Community 👩‍💻👨‍💻 and was authored by Xavier Hurst
I wanted to improve the security of my SSH keys, which are currently only protected by a passphrase. Likewise, I also wanted to ease their migration when I configure a new machine. I used resident keys and a YubiKey to do both.
Resident keys or discoverable credentials mean that the private key is stored in persistent memory on a FIDO authenticator like a YubiKey. This has two advantages. First, if the authenticator is not connected to the computer, the key cannot be used. Second, if you carry your authenticator with you, you can import the key on any machine that has a compatible version of OpenSSH (8.2 or above).
Yet, setting this up is more complex than it should be, at least on macOS.
Generating a resident key pair
The OpenSSH bundled with macOS can not generate resident keys, despite being compatible with them. This is due to a compilation flag that disables this option (--disable-security-key). To work around this, we'll install the latest version of OpenSSH using homebrew:
brew install openssh
Generating a resident key pair is quite similar to how you're used to generate and use SSH keys. The main difference is that the keys will be stored on the YubiKey (resident). Note that a YubiKey 5 can store up to 25 resident keys.
To store a resident key, the Yubikey must have firmware 5.2.3 or above and a PIN configured.
In a terminal window, type the following command:
ssh-keygen -t ed25519-sk -O application=ssh:personal -O no-touch-required -O resident
Let's dive into the different parameters.
-
-t ed25519-skis the key type, two options are possibleecdsa-skanded25519-sk(skstands for security key). If you do not know which one to choose, stick withed25519-sk -
-O application=ssh:*names the key, so you can identify it more easily later, very handy if you generate a few
-
-O no-touch-requiredprevents you from having to touch the YubiKey every time you want to use the key -
-O residenttells OpenSSH to store the key on the YubiKey
Just like you would expect, ssh-keygen created two files on your local machine:
-
id_ed25519_skis the private key. But, it's a key handle that can only be used with the YubiKey, making it unusable without it. The "real" private key is stored on the YubiKey. Meaning that you'll need to have the YubiKey plugged into your computer to be able to use it. The YubiKey, in this case, acts as a second authentication factor. -
id_ed25519_sk.pubis the public key
Adding your SSH key to the ssh-agent
Even though we've installed the latest version of OpenSSH, the default ssh-agent bundled with macOS is still running. This agent is not capable of loading resident keys. To tackle this issue, we'll install Funtoo Keychain to run and manage our own agent from the version of OpenSSH we just installed.
brew install keychain
You now need to eval Keychain before you can load a resident key.
source (keychain --eval --noinherit -q | psub)
That's it!
Importing your SSH key on another machine
One of the biggest advantages of resident keys is that they can be imported from a YubiKey. This allows you to securely transfer them from one computer to another. To do this, we have two options:
- Use
ssh-add -Kto load all resident keys from a YubiKey into yourssh-agent - Use
ssh-keygen -Kto download all resident keys from a YubiKey and write them to your current directory. In this scenario,ssh-agentwill be able to load the keys from your disk which is more suitable for permanent use.
As you can see, the downloaded key has an _rk_personal suffix. The rk part is there to remind you that it's a resident key, and personal is its name.
By default, OpenSSH will look for these paths to automatically load private keys:
~/.ssh/id_dsa~/.ssh/id_ecdsa~/.ssh/id_ecdsa_sk~/.ssh/id_ed25519~/.ssh/id_ed25519_sk~/.ssh/id_rsa
Hence, _rk_personal must be removed from the filename for the key to be automatically loaded. If you want to keep this suffix, specify its path in your ~/.ssh/config.
Due to the current implementation of resident keys in OpenSSH, the
no-touch-requiredflag is not restored when importing keys from a YubiKey. This flag will only be available with the original private key handle.
Using it
Git
Like normal ssh keys, resident keys are usable for git operations. Add the public key to your profile of your favorite git service and you're good to go.
At the time of writing, Gitea, GitHub and GitLab do not support
no-touch-required. You'll have to touch the YubiKey for each git operation.
SSH
Using a resident key for SSH is the same as using a regular key. Add the public key to your authorized_keys and you’re good to go. If the resident key was generated with no-touch-required, prepend this option to the public key.
~/.ssh/authorized_keys
# Without `no-touch-required` option
sk-ssh-ed25519@openssh.com ...
# With `no-touch-required` option
no-touch-required sk-ssh-ed25519@openssh.com ...
References
- macOS: Enable security keys
- Gitea: Support for
no-touch-required - GitHub: Support for
no-touch-required - GitLab: Support for FIDO2
- no-touch-required flag not restored from hardware token
- Securing SSH with FIDO2
This content originally appeared on DEV Community 👩‍💻👨‍💻 and was authored by Xavier Hurst
Xavier Hurst | Sciencx (2022-10-19T16:07:01+00:00) Using YubiKey resident keys for Git and SSH on macOS. Retrieved from https://www.scien.cx/2022/10/19/using-yubikey-resident-keys-for-git-and-ssh-on-macos/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.