Before starting to use the PIV functionality of a YubiKey, it is important to change the PIN, PUK and Management keys from their default values. See Admin access for details on what these unlock. For typical usage, you will want to memorize the PIN, and keep a copy of the PUK and Management keys in a secure location.
YubiKey PIV Manager will automatically prompt you to initialize the device by setting the PIN, PUK, and Management Keys when it detects a YubiKey which is using the default values. Follow the on-screen instructions to set new values for your YubiKey. The YubiKey PIV Manager presents you with an option to only set the PIN and not set a PUK or Management Key. This can be more convenient, but also less secure. Also note that this scheme is not compatible with other tools. Do not select this option if you are planning on changing any of these keys using tools other than the YubiKey PIV Manager (this includes yubico-piv-tool). For more information on this mode, see PIN and Management Key.
The Management Key is set by invoking the
set-mgm-key action. You will need
to provide the currently set Management Key (using
--key), and the new key to
--new-key). If the default Management Key is currently set you may omit
--key argument. Keys are provided as 24-byte hex strings, and should be
key=$(export LC_CTYPE=C; dd if=/dev/urandom 2>/dev/null | tr -d '[:lower:]' | tr -cd '[:xdigit:]' | fold -w48 | head -1) echo $key yubico-piv-tool -a set-mgm-key --new-key=$key --key=010203040506070801020304050607080102030405060708
Changing the PIN is done by invoking the
change-pin action and providing the
current PIN (using the
-P argument), and a new PIN to set (using
yubico-piv-tool -a change-pin -P 123456 -N <NEW PIN>
Changing the PUK is done by invoking the
change-puk action and providing the
current PUK (using the
-P argument), and a new PUK to set (using
yubico-piv-tool -a change-puk -P 12345678 -N <NEW PUK>
If the wrong PIN is entered 3 times consecutively, the PIN will become blocked. Once blocked, the PIN cannot be used. To recover from this state you can provide the PUK to set a new PIN, which will then not be blocked.
For the YubiKey PIV Manager this is done by opening the Manage device PINs window. If PIN is blocked there will be a button titled Reset PIN, which will let you do this.
To set a new PIN using yubico-piv-tool you invoke the
unblock-pin action and
provide the PUK (using
-P) and a new PIN to set (using
yubico-piv-tool -a unblock-pin -P 12345678 -N <NEW PIN>
If you’ve lost your Management Key the only way to recover is to completely reset the PIV functionality, which will erase any keys or certificates stored on the device and set the default PIN, PUK and Management Key. This will only affect the PIV portion of your YubiKey, so any non-PIV configuration will remain intact. Resetting the PIV functionality is only possibly when both the PIN and PUK have been blocked.
For the YubiKey PIV Manager this is done by opening the Manage device PINs window. If both the PIN and PUK are blocked there will be a button titled Reset device. If this button is not visible you will likely have to use the Change PIN and/or Change PUK buttons to block them by providing incorrect values until they are both blocked. After resetting you will be prompted to initialize your YubiKey again.
To reset PIV on your YubiKey using yubico-piv-manager you invoke the
action. To ensure that both the PIN and PUK are in a blocked state, you can run
the following commands:
# Attempt to use an invalid PIN multiple times to block it # yubico-piv-tool -a verify-pin -P 000000 yubico-piv-tool -a verify-pin -P 000000 yubico-piv-tool -a verify-pin -P 000000 yubico-piv-tool -a verify-pin -P 000000
# Attempt to change PUK using an invalid PUK multiple times to block it # yubico-piv-tool -a change-puk -P 000000 -N 000001 yubico-piv-tool -a change-puk -P 000000 -N 000001 yubico-piv-tool -a change-puk -P 000000 -N 000001 yubico-piv-tool -a change-puk -P 000000 -N 000001
Once PIN and PUK are both blocked, you can reset the YubiKey.
yubico-piv-tool -a reset