⭕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.
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.
❊ PIV PINs
First, we'll adjust the settings of your PIV interface and set up some custom PINs.
Launch Command Prompt, Powershell, or Terminal.
PIN RETRIES 
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:
ykman piv access set-retries 5 5First number is retries for PIN. Second number is retries for PUK.
PIN
Now we'll change your PIV PIN by executing:
ykman piv access change-pinWhen prompted for the current PIN, type 123456
PUK
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:
ykman piv access change-pukWhen prompted for the current PUK, type 12345678
For a complete description of this command, view the docs.
MANAGEMENT KEY
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.
ykman piv access change-management-key -g -pWhen prompted for your current management key, type 010203040506070801020304050607080102030405060708
❊ GPG PINs
We will now adjust the PINs associated to the GPG interface.
PIN RETRIES
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.
ykman openpgp access set-retries 10 5 10PIN attempts, RESET CODE attempts, ADMIN PIN attempts.
Click the read docs button above for more info.
PINS
Changing the PINs for GPG are a bit different.
Type the following commands:
gpg --card-editWait until you see the text gpg/card>and then type:
adminYou should see the text Admin commands are allowed, and then finally, type:
passwdYou are now in admin mode for GPG and should see the following:
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quitYou 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:
ykman openpgp info
❊ 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 :
listYou 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:
nameYou should be prompted with the following:
gpg/card> name
Cardholder's surname: John
Cardholder's given name: DoeAfter 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:
Name of cardholder: Doe JohnLOGIN NAME
Change the login name you wish to use when the PIN dialog appears on some interfaces:
loginOnce changed, it will appear in the list command as:
Login data .......: aetherinoxLANGUAGE
Changes the language for your nationality:
langOnce changed, it will appear in the list command as:
Language prefs ...: enGENDER / SALUATION
Changes the salutation used such as Mr. or Ms.
sexOnce changed, it will appear in the list command as:
Salutation .......: Mr.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.
urlYou can input something like
https://github.com/yourusername.gpgOnce changed, it will appear in the list command as:
URL of public key : https://github.com/yourusername.gpgOnce 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:
ykman openpgp 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.
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:
ykman openpgp keys set-touch sig on
ykman openpgp keys set-touch enc on
ykman openpgp keys set-touch aut on
ykman openpgp keys set-touch att onUIF
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
$ gpg --card-statusIn the long list of printed text, search for
UIF setting ......: Sign=off Decrypt=off Auth=offTo change the settings for this, type:
$ gpg --card-edit
adminOnce you enter gpg admin, execute the commands:
uif 1 on
uif 2 on
uif 3 onYou can then quit gpg edit, and go back to card-status and confirm your UIF settings:
gpg/card> quit
$ gpg --card-status
--------------------------------------------
PIN retry counter : 10 10 10
Signature counter : 0
KDF setting ......: off
UIF setting ......: Sign=on Decrypt=on Auth=onAll 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 --card-edit
admin
forcesig❊ 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 --card-edit
admin
kdf-setup❊ GPG Reset
If you've messed something up, or wish to start over, you can reset GPG with the command:
ykman openpgp reset❊ 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
ykman config set-lock-code --generate
Using a randomly generated lock code: cce9181f4a97bac00459419986510d40
Lock configuration with this lock code? [y/N]: ySPECIFY NEW LOCK CODE
ykman config set-lock-code --new-lock-code HEX❊ MODIFY OTP SLOTS
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.
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
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 Bitwarden.
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.
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.
ykman otp settings 1 --no-enter
ykman otp settings 2 --no-enter❊ 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
Was this helpful?