⭕Setting up a New Key
What to do with your first Yubikey. A complete guide to setting it up.
Last updated
What to do with your first Yubikey. A complete guide to setting it up.
Last updated
This guide gives a straight-forward series of instructions for setting up many aspects of your new Yubikey 5 series security device.
It will be straight to the point in regards to commands to enter, etc. If you are unsure of how to execute ykman or gpg commands, please review the references listed below before continuing with this guide:
Instructions on how to configure the command-line
Instructions on how to configure GPG
Download Yubikey Manager
Explains what GPG is.
Explains what PIV is.
A complete guide to the different Yubikey PINs.
Make sure your Yubikey is plugged into the USB port on your computer.
If you wish to skip all of the lengthy descriptions below, you can view this same list of commands on the Minimal Version page.
First, we'll adjust the settings of your PIV interface and set up some custom PINs.
Launch Command Prompt, Powershell, or Terminal.
This is the number of total times you can incorrectly enter a PIN before you are locked out. Once your PIN is locked out, you'll need to use your PUK to unlock your PIN.
By default, the total number of retries allowed on your PIN and PUK is 3 failures each.
To change the number of retries:
First number is retries for PIN. Second number is retries for PUK.
Now we'll change your PIV PIN by executing:
When prompted for the current PIN, type 123456
Your PUK is your Personal Unlocking Key. This is only used if you are locked out by typing an incorrect PIN too many times. This will reset your PIN retry count.
Change your PIV PUK by executing:
When prompted for the current PUK, type 12345678
Your management key will be requested any time you import new certificates to your PIV interface. This is for admin actions.
You have two options below. You can let the system generate a brand new management key, or you can specify your own.
When prompted for your current management key, type 010203040506070801020304050607080102030405060708
We will now adjust the PINs associated to the GPG interface.
This is the number of total times you can incorrectly enter your GPG PINs before you are locked out.
This number is present when you type gpg --card-status OR list if you are in gpg edit mode.
PIN attempts, RESET CODE attempts, ADMIN PIN attempts.
Changing the PINs for GPG are a bit different.
Type the following commands:
Wait until you see the text gpg/card>and then type:
You should see the text Admin commands are allowed, and then finally, type:
You are now in admin mode for GPG and should see the following:
You want to select 1and3.
After you press 1, follow the instructions to change that PIN, then proceed to 3.
Once finished, press Q
If you wish to see how many retries are left on your key, type:
If you followed along from the last command, you should see gpg/card>
If you do not, type gpg --card-editand then the wordadmin
We are now going to customize the GPG interface of your card to display your own information.
To see what is currently registered on the card, type :
You should see something similar to the following below:
This is all the information associated with your GPG interface.
We're going to change some of the information to be customized for you.
First we'll change your name by typing:
You should be prompted with the following:
After editing, you'll be prompted for the ADMIN PIN which we explained how to change above. If you did not change it, then the default will be 12345678
If you type the word list now, you should see the following:
Change the login name you wish to use when the PIN dialog appears on some interfaces:
Once changed, it will appear in the list command as:
Changes the language for your nationality:
Once changed, it will appear in the list command as:
Changes the salutation used such as Mr. or Ms.
Once changed, it will appear in the list command as:
This is where you have a public gpg key saved. You can skip this if you do not have one yet. Github.com offers public key hosting if you generate and upload a GPG key to Github's settings.
You can input something like
Once changed, it will appear in the list command as:
Once you are finished with these settings, type Q for quit.
This is how you'll configure your yubikey if you want the key to make you touch the gold circle when using any of your 4 types of GPG keys.
To see how your touch policies are currently configured, type:
If you use the Signature (SIG) key to sign an Adobe file, or give a digital signature anywhere, it will ask you to touch the key before completing.
If you use the Encryption (ENC) key to encrypt files, it will require you to touch the key.
If you use the Authentication (AUT) key for tasks such as SSH authentication, it will ask you to touch the key before connecting.
If you use an Attestation (ATT) key to certify your other keys, it will request that you touch the Yubikey first.
To enable touch policies on any of these GPG keys, type the following:
The second place you must set your touch policy are within GPG itself. This will be utilized when you use GPG applications such as Kleopatra.
Open Command Prompt and type
In the long list of printed text, search for
To change the settings for this, type:
Once you enter gpg admin, execute the commands:
You can then quit gpg edit, and go back to card-status and confirm your UIF settings:
All UIF settings should be set to on now.
When set to "forced", gpg requests the entry of a PIN for each signature operation. When set to "non forced", gpg may cache the PIN as long as the card has not been removed from the reader.
To enable KDF, you must enable this before any GPG keys are imported on your Yubikey. If you import GPG keys before enabling KDF and attempt to enable KDF later; you will receive the error:
gpg: error for setup KDF: Conditions of use not satisfied
If you've messed something up, or wish to start over, you can reset GPG with the command:
At present time, there appears to be NO way to reset this if you forget the code. You will be completely unable to ever change settings on your Yubikey again. Use at your own risk.
A lock code may be used to protect the application configuration. The lock code must be a 32 characters (16 bytes) hex value.
Once in, at the top select Applications -> OTP.
You should now be presented with two slot options to choose from:
Your Yubikey has two slots that you can program. These slots are linked to the gold circle in the middle of your Yubikey.
Tapping the circle will perform whatever action you've programmed into SLOT 1. Holding the circle for a few seconds will perform the task programmed in SLOT 2.
SLOT 1
Between 0.3 -> 1.5 seconds
SLOT 2
Between 2 -> 5 seconds
Unchanging string of characters. Password will output if you place cursor in password field to website or service and tab your Yubikey.
HMAC-based one-time passwords which is 6 or 8 digit.
By default, SLOT 1 is configured to use Yuibico OTP. You can however, change these to whichever methods you prefer.
Most people seem to enjoy the Static Password option the most as it helps with not having to remember a complex password that you can insert anywhere by simply touching your Yubikey.
Disables the Yubikey from automatically pressing "Enter" each time slot 1 or 2 is pressed.
That option is completely up to you. Yubikeys are a very powerful device that can do a wide variety of tasks.
Take a look at our Tutorials section to the left and click on something that interests you.
Click the read docs button above for more info.
When creating a GPG keypair, you'll create one for Signature, one for Encryption, one for Authentication and a new feature for Yubikey includes an Attestation key. To learn about Attestation, view the docs here.
We will now get out of the command-line stuff and utilize the Yubikey Manager software. The next steps can indeed be done in the command-line, but I'd like to keep this simple.
Launch Yubikey Manager.
When you click you will be presented with a few options:
Unique 44-character string that is generated by the YubiKey when it is touched or scanned by NFC. Supported by services such as .
YubiKey receives the challenge and encrypts it with a stored secret key. It is then sent back to the host for authentication. It can be used in single and multi-factor authentication for logging into applications or devices. This is useful for programs such as KeePassXC.
