Entertainment at it's peak. The news is by your side.

Yubikey Setup Guide for Software Developers



Within the past year Yubico has up to this point their firmware to toughen Ed25519. This in the slay brings toughen for elliptical curve encryption, and much shorter ssh public keys.

Yubikeys are actually considerable, they enable you to manufacture git commit signing, ssh, and retailer your non-public key on an external instrument.

This skill that you just can soar between computer techniques without considerations, and you never non-public your non-public key sitting on a neighborhood filesystem.

One severe allotment to this setup is making backup keys, this has been lined by assorted weblog posts, but there’s a much less unique topic available: plugging in a cloned key will space off a GPG error that you just could work around to your non-public… This is frustrating at the same time as you setup two yubikeys, and regularly relate them every.

This recordsdata will duvet increasing the GPG master key. Environment it up for commit signing, the utilization of this master key with ssh, how to variety backups, and how to setup multiple computer techniques. Sadly or no longer it’s a ways moderately waiting for learners, but once you may maybe maybe maybe moreover simply non-public this machine setup, you are left with an extremely safe SSH + GPG resolution!

Getting Started

Or no longer it’s a ways a must must eliminate a Yubikey that used to be made after November 2019. That is around the time that 5.2.3 got right here out. That you can learn more about it right here. This firmware version added toughen for curve25519. I even non-public extinct the 5CI, 5C nano, 5C, 5 NFC, and the fresh 5C NFC. I’ve duplicated my master key across every of my keys. I highly counsel you procure no longer no longer as much as 2 keys, so as that at the same time as you lose one you may maybe maybe maybe moreover very correctly be no longer locked out of servers or assorted techniques.

Let’s delivery by installing the gpg tooling. Be definite that to manufacture this step on every computer that you just conception to relate your Yubikey with!

brew set up gnupg pinentry-mac

Whilst you are no longer working a mac, be definite that to salvage the gnupg utility for your OS.

Generating the Master Key

This would well be the master GPG key for all of our Yubikeys, our ssh key’s moreover derived from it. Birth up a terminal, and create a brand fresh listing. I’ll relate a folder known as gpg and may maybe maybe moreover simply quiet reference it later. Then hobble the next:

gpg --knowledgeable --stout-gen-key

Now that we’re within the gpg application, consume 9 for ECC. Followed by 1 for curve25519.

I are inclined to selected 0 on the subsequent step, so as that my key never expires. This would well then demand for your identify and email take care of, then you definately can hit “O” for k.

The final step is a fast to come by a password. Be definite that to come by one thing lengthy and very random. I wrote my secret key down on paper for safe holding. It’s most likely you need to retype this secret key quite a bit sadly. 3 instances per yubikey in picture to copy it over, so invent no longer neglect it!

Adding subkeys

It’s most likely you’ll well maybe moreover simply quiet now leer a line outputted after its creation that looks to be admire this:

gpg: key A5CA05BB6F4730D4 marked as in a roundabout procedure trusted

To variety our next steps simpler to comply with, please hobble this in your terminal:

echo "A5CA05BB6F4730D4" >> keyid

Substitute the important thing identification above along with your non-public. We’re simply throwing it correct into a file in the present folder for safe holding.

We’ve to create authentication and signature subkeys earlier than our master key’s total.

gpg --knowledgeable --edit-key $(cat keyid)

Now we’re within the gpg application and want to manufacture the next:

come by "11" ECC (space your non-public capabilities)
come by "A" Toggle the authenticate skill
form "Q"
come by "1" Curve 25519

After that, you may maybe maybe well maybe space the expiration, after which form in your secret key to manufacture increasing the sub key. We’ve to manufacture it once again for the signing key:

come by "10" ECC (stamp correct)
come by "1" Curve 25519

Attach expiration, and come by yes to create, after which yes again to basically create it….. these gpg instruments are no longer very person fine are they?

K! We did it… we created the keys and easily want to form achieve to earn out of the gpg application. We can in the slay transfer on.

Exporting the Key

Inner your gpg folder, hobble the next:

gpg --armor --export-secret-keys $(cat keyid) > mastersub.key
gpg --armor --export-secret-subkeys $(cat keyid) > sub.key
gpg --armor --export $(cat keyid) > public.key

We’ve successfully exported our key, and the corresponding gpg public key. This would well be wanted later when we setup commit signing.


be definite that to variety a zipper file of your gpg folder that we ran the instructions interior of. You will must non-public the next files interior:


This zip file ( wants to be backed up offline to a usb force, or assorted safe location. It’s moreover major, because every time we transfer our gpg key over to a yubikey, the gpg application destroys the important thing. So now we must copy over a reproduction every time.

Facet demonstrate… right here is but one more annoyance with the gpg application. I am attempting to variety this recordsdata as straight ahead as I’m in a position to, it took me perpetually to manufacture all of this attributable to how overly refined the gpg instruments are. Fortunately some core contributors are rewriting the spec in rust.

Organising your Yubikey

We will transfer on to getting our yubikey ready! We delivery by configuring it. GPG recognizes Yubikeys as colorful cards:

gpg --card-edit

On this fast, you may maybe maybe want to come by 1 to commerce the pin. When the fast comes up, form 123456 for the present pin, right here is the default for yubikeys. After, space a safe password. This would well be extinct to free up the secret key to your Yubikey for ssh or gpg utilization. I make a selection to preserve up mine roughly short, but moreover one thing that can no longer too easy.

After that, form 3. This time now we must commerce the admin pin. The initial pin is 12345678. I are inclined to relate the equivalent pin for admin and unique pins. I moreover relate the equivalent pin on every of my backup yubikeys, so as that I invent no longer by accident earn locked out. After that is accomplished, form q, then there’s a few additional instructions you may maybe maybe well maybe space at the same time as you could must:


Sooner than we add the keys to our Yubikey, there are a couple no longer mandatory setup steps. Whilst you could must, you may maybe maybe well maybe slip salvage Yubikey Supervisor CLI. And hobble these instructions:

ykman openpgp space-contact aut off
ykman openpgp space-contact sig on
ykman openpgp space-contact enc on

Or no longer it’s as much as you to space these to on or off. This is simply telling your yubikey that any authentication, signature, or encryption key utilization, requires a bodily contact of the instrument earlier than this can manufacture the operation. This would well be considerable for ultra safety unsleeping participants. A program would no longer be in an arena to stamp or encrypt anything along with your key in the background, because it may maybe maybe most likely well require a contact earlier than any action.

The final thing I are inclined to manufacture, is set up up the Yubikey Supervisor GUI, slip to Suggestions -> OTP, and disabled the short contact action. This is on by default and at the same time as you bump it at some stage in a slack message, it may maybe maybe most likely well moreover even be actually irregular sending these authenticator codes by chance.

I make a selection to configure the lengthy contact action with a static password, I’ll come by one thing actually random, but relate it across all of my backup keys. If I am on a public computer without access to 1Password, I’m in a position to relate it as a safe password option, otherwise you may maybe maybe maybe moreover even retailer your 1Password secret key right here.

Oh, and earlier than I neglect, you may maybe maybe well maybe moreover slip to Suggestions -> FIDO2 and space a pin there. This would well be extinct for Webauthn when supported. Whilst you consume your Yubikey for 2FA on the discover, this can require a pin, this protects you from somebody stealing your yubikey and attempting to relate it to access a provider online, they would moreover want your pin. Also demonstrate that right here is separate, and no longer the equivalent because the GPG colorful card pin we created earlier. All these specs in one instrument…. complicated huh?

There may maybe be so mighty these keys can manufacture, and its spread across wayyyy too many applications and configurations!

Adding to a Yubikey

This piece may maybe maybe moreover even be adopted again for every Yubikey that you just actually want to relate. These will be valid clones with the master key on them, and may maybe maybe moreover simply quiet record the equivalent ssh public key at any time at the same time as you manufacture this direction of.

Or no longer it’s a ways a must must hobble the next instructions launch air of the gpg listing that we created in the important thing creation step.

Your present listing must non-public in it. Originate by unarchiving the that we created earlier. Every time you manufacture this piece (for every key) you could delete the gpg folder, and unarchive again. We cannot reuse the gpg folder every time, since the gpg colorful card instructions delete the secret key, so you MUST non-public a fresh copy of the gpg files every time.

# unzip
export GNUPGHOME=$(mktemp -d)
cp -r gpg $GNUPGHOME

gpg --import mastersub.key
gpg --edit-key $(cat keyid)

Now we delivery up copying every of the three keys off the cardboard. Or no longer it’s a ways moderately verbose, so right here’s the manner you manufacture it:

key 1
keytocard (come by encryption, 1)
key 1

key 2
keytocard (signature)
key 2

key 3
keytocard (auth)
key 3

GPG makes you consume the important thing, then after doing keytocard you could deselect it by typing the equivalent thing again. It now and again says “operation no longer supported by instrument” after you manufacture the initial yubikey setup and hobble the keytocard justify. Stunning unplug your yubikey, then drag it motivate in, form keytocard again, and it may maybe maybe most likely well moreover simply quiet existing the important thing different menu.

Every time you manufacture keytocard you may maybe maybe must enter the master key’s secret key that you just wrote down earlier, adopted by the cardboard’s admin pin that you just space. Adore I said, colorful verbose, and may maybe maybe make a selection some time at the same time as you may maybe maybe maybe moreover simply non-public a actually lengthy secret key!

After this step is total, your yubikey is able to head.

Organising GPG Signing

This direction of wants to be accomplished on every computer that you just actually want to manufacture commit signing on.

git config --worldwide person.signingkey $(cat keyid)
git config --worldwide commit.gpgsign upright
gpg --import public.key

The final justify is the largest piece. You will must import the general public key from your gpg master key, in every other case git gained’t look for your yubikey. Produce no longer demand how many hours I spent being puzzled as to why this didn’t work on my 2nd computer the first time 😛  

Be definite that to add the contents of our public.key file to GitHub or assorted provider, so as that your commits will existing as verified.

Utilizing SSH

On a Mac you could manufacture the next:

vi ~/.gnupg/gpg-agent.conf

the contents are:

pinentry-program /usr/local/bin/pinentry-mac

This would well be assorted on assorted OS’s. Please scrutinize up “gpg agent ssh setup” for your OS at the same time as you may maybe maybe maybe moreover very correctly be no longer on Mac.

Now, edit your .bashrc, .zshrc, and so on, reckoning on what shell you consume, with the next:

export "GPG_TTY=$(tty)"
export "SSH_AUTH_SOCK=${HOME}/.gnupg/S.gpg-agent.ssh"
gpgconf --launch gpg-agent

Be definite that to unplug and replug your yubikey in at the same time as you neutral copied the keys over to it. Re-launch your terminal (or source ~/.zshrc) after which this justify may maybe maybe moreover simply quiet work:

ssh-add -L

It is going to moreover simply quiet checklist your public key, which is derived from your master gpg key! It’s most likely you’ll sight cardno:xxxx at the cease, at the same time as you may maybe maybe maybe moreover simply non-public assorted present keys. Add this to github or any server simply admire any assorted ssh key may maybe maybe well be extinct.

Utilizing Duplicated Keys

Dawdle in your first key, strive and ssh, or variety a git commit. Whilst you manufacture that, make a selection it and drag in your 2nd key. Whilst you strive and manufacture the equivalent thing, the GPG agent will bitch, and notify Please insert card no XXX. It wants you to insert the first card… Or no longer it’s very anxious because our 2nd card has our key on it and may maybe maybe moreover simply slip.

You non-public to restart the agent to earn it to work anytime you swap cards. I added a feature to my ~/.zshrc

resetcard() {
  rm -r ~/.gnupg/non-public-keys-v1.d
  gpgconf --abolish gpg-agent
  gpg --card-feature

Anytime you leer the Please insert card error, form resetcard in your terminal, after which this can work. For some reason the GPG agent assessments the cardboard quantity with the SSH public key and wants to refuse to relate the 2nd card until you manufacture this. With this tiny fix, you are in an arena to relate any of your keys in any of your gadgets. All of them work the equivalent, and you may maybe maybe maybe moreover never must generate a brand fresh SSH key to your computer again!


Thanks for reading by this recordsdata, I’m hoping it helped somebody available. I’ve spent countless hours setting these up over the years, and wanted a better reference. I desire the gpg tooling would precisely toughen reproduction keys, and variety the setup direction of moderately simpler. Yubico moreover requires you to salvage the CLI application for some setup steps, and the GUI has assorted sets of alternatives. The ecosystem is colorful scattered. Or no longer it’s moreover unhappy we must configure the gpg agent manually to toughen ssh utilization. I would admire for it to “simply work” suddenly with none setup, and to include the mandatory pin-entry program robotically. Presumably at some point we are going to earn there…

Whilst you may maybe maybe maybe moreover simply non-public your keys setup and cloned, it’s correct a few instructions to non-public git commit signing on a brand fresh computer, and some more configuration alternatives to toughen ssh, so or no longer it’s no longer too inaccurate. The initial direction of is A LOT even though. I cannot give it some idea took 2300+ phrases to level it all.

Indubitably feel free to ship me any questions @zachcodes on twitter 🙂

Read More

Leave A Reply

Your email address will not be published.