⭕Setting up a New Key
What to do with your first Yubikey. A complete guide to setting it up.
This guide gives a straight-forward series of instructions for setting up many aspects of your new Yubikey 5 series security device.
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.
❊ PIV PINs
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
❊ GPG PINs
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.
PINS
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:
❊ Personal Information
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.
NAME
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:
LOGIN NAME
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:
LANGUAGE
Changes the language for your nationality:
Once changed, it will appear in the list command as:
GENDER / SALUATION
Changes the salutation used such as Mr. or Ms.
Once changed, it will appear in the list command as:
PUBLIC KEY URL
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.
❊ GPG Touch Policies
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.
OPENPGP INFO
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:
UIF
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.
❊ GPG Signature PIN
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.
❊ GPG KDF-Setup
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
❊ GPG Reset
If you've messed something up, or wish to start over, you can reset GPG with the command:
❊ LOCK CODE
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.
GENERATE NEW CODE
SPECIFY NEW LOCK CODE
❊ MODIFY OTP SLOTS
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.
| Press TIme | |
|---|---|
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.
OTP SLOT | NO ENTER
Disables the Yubikey from automatically pressing "Enter" each time slot 1 or 2 is pressed.
❊ What's Next?
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.
Last updated
