Installing and Managing the Yubikey Manager on Ubuntu

How-To: Yubikey Advanced

6th November 2023

The Yubikey Manager is a CLI tool for mainly managing your PIV = Personal Identity Verification storage, where you can store certificates and private keys. But you can also configure all the other Yubikey features like FIDO and OTP. This guide will show you how to install it on Ubuntu 22.04 and show some initial configuration to get started.

Note: There is a GUI version to. However, the CLI configuration is pretty easy to get a grip on so at least for me it’s unnecessary.

Installing The Yubikey Manager

Pre-requisites

Packets required in Ubuntu for smart card readers to work properly

sudo apt update && sudo apt upgrade --yes
sudo apt install opensc-pkcs11 libpam-pkcs11 pcscd

Source: https://ubuntu.com/server/docs/security-smart-cards

Install the Yubikey udev rules

sudo apt install libu2f-udev

Source: https://support.yubico.com/hc/en-us/articles/360013708900

Install some FIDO2 middleware

These are useful for U2F authentication:

sudo apt install libfido2-1 libfido2-dev libfido2-doc fido2-tools

Note: these will be needed later for OpenSSH key generation.

Install the Yubikey Manager

Add the required repository to get the latest version and then install the Yubikey manager:

sudo apt-add-repository ppa:yubico/stable
sudo apt update
sudo apt install yubikey-manager

Then reboot your PC.

Yubikey Configuration

Required PIV Settings

You need to set some initial configuration before you can manage keys and certificates.

Check firmware of your yubikey

$ ykman list
YubiKey 5C Nano (5.4.3) [OTP+FIDO+CCID] Serial: XXXXXXXX

Note: It is not possible to do a software upgrade on a yubikey. Minimum version for Ed25519 key support is 5.2.3. If your Yubikey is older than that, you need to do a hardware upgrade.

Ykman Help

To get information about any ykman commands, just append “-h” to the end of the command. For example:

ykman piv -h

user@computer:~$ ykman piv -h
Usage: ykman piv [OPTIONS] COMMAND [ARGS]...

  Manage the PIV application.

  Examples:

    Generate an ECC P-256 private key and a self-signed certificate in
    slot 9a:
    $ ykman piv keys generate --algorithm ECCP256 9a pubkey.pem
    $ ykman piv certificates generate --subject "CN=yubico" 9a pubkey.pem

    Change the PIN from 123456 to 654321:
    $ ykman piv access change-pin --pin 123456 --new-pin 654321

    Reset all PIV data and restore default settings:
    $ ykman piv reset

Options:
  -h, --help  show this message and exit

Commands:
  info          display general status of the PIV application
  reset         reset all PIV data
  access        manage PIN, PUK, and Management Key
  certificates  manage certificates
  keys          manage private keys
  objects       manage PIV data objects

You also have Yubicos command reference here:
https://docs.yubico.com/software/yubikey/tools/ykman/PIV_Commands.html

View PIV info

To view existing certificates and keys on your Yubikey:

ykman piv info

Note: Sometimes you just need to remove your Yubikey and reconnect it for ykman piv info command to work.

Reset PIV

I have an old certificate installed from before so I’m going to reset the PIV module so I will start from scratch.

ykman piv reset

Set a new PIN code

If you read the help screen, you already know:

ykman piv access change-pin --pin 123456 --new-pin XXXXXX

Note: default is 123456

Set a new PUK code

PUK code can help recover your PIV data if you forget your PIN or it gets blocked

ykman piv access change-puk --puk 12345678 --new-puk XXXXXXXX

Note: the PUK code have to be 6-8 characters long and can combine numbers and letters. Default PUK is 12345678.

Set a Management Key

Management functionality is guarded by a management key. This key is required for administrative tasks, such as generating key pairs. A random key may be generated and stored on the YubiKey, protected by PIN.

ykman piv access change-management-key --algorithm AES256 --protect --generate --pin XXXXXX --touch

Import Certificate

I put the help screen up here:

user@computer:~$ ykman piv certificates import -h
Usage: ykman piv certificates import [OPTIONS] SLOT CERTIFICATE

  Import an X.509 certificate.

  Write a certificate to one of the PIV slots on the YubiKey.

  SLOT            PIV slot of the certificate
  CERTIFICATE     file containing the certificate (use '-' to use stdin)

Options:
  -m, --management-key TEXT  the management key
  -P, --pin TEXT             PIN code
  -p, --password TEXT        a password may be needed to decrypt the data
  -v, --verify               verify that the certificate matches the private key in the slot
  -h, --help                 show this message and exit

This is an example of importing a EJBCA superadmin certificate:

ykman piv certificates import --pin XXXXXX --password XXXXXXX 9a /home/user/superadmin.p12

Note: Check available PIV slots and what purpose they have: https://developers.yubico.com/PIV/Introduction/Certificate_slots.html

Where to go from here

So what’s the point of it all? Like I mentioned just above, one use-case is that you can now use your Yubikey as a smart card for authenticating yourself on systems that requires it. In an upcoming post I will show how to use FIDO authentication with SSH.