3 - Yubikey

3 - Yubikey

December 31, 2024
Security
Yubikey, Github

Result #

1. Update Yubikey Firmware #

It is not possible to update any Yubikey’s to the latest version: YubiKey Firmware is Not Upgradeable.

It is possible to find the current version using this guide: Where to find YubiKey Firmware Version.

Note: Quick and dirty command; assuming you have yubikey-manager installed: ykman info.

2. Factory Reset YubiKey #

I compiled all the information within this documentation: Factory Reset Components.

Note: Non-Resident SSH Keys will be stored in FIDO Component.

3. Generate SSH Key #

IMPORTANT: Make sure the Security Key is inserted before running!

Generate an SSH Key for use: Generating a new SSH key

ssh-keygen -t ed25519-sk -C "<COMMENT>"

4. Import Public Key into Github #

Copy the contents of the .pub file and it import into Github, following these steps.

Note: Make sure you use a different SSH Key for Authentication via CLI.

5. Test with SSH #

ssh -T git@github.com

6. Clone Repository with SSH #

git clone ssh://git@ssh.github.com:443/<YOUR-USERNAME>/<YOUR-REPOSITORY>.git

7. Configure Git to Sign Commits and Tags with SSH #

git config gpg.format ssh

8. Let Git know the .pub SSH Key #

git config user.signingkey /PATH/TO/.SSH/KEY.PUB

9. Sign (test) Commit #

git commit -S -m "(Test)"

Experience #

The primary goal is to allow me to sign my commits in a Git Repository, specifically Github.

Github #

Each way of accessing GitHub supports different modes of authentication.

  • Username and password with two-factor authentication, or a passkey
  • Personal access token
  • SSH key

Source: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#about-authentication-to-github

Session 1 #

The first session was to get a brief overview of what a YubiKey is. I knew it’s a device that provides 2-factor authentication in different ways; that was the extent of my knowledge.

Session 2 #

After taking some time away from this project, I pushed myself to get back to this project. I had to go back to square one; I not only asked the same question from Session 1 with different wording but I also asked a question to narrow down my specific use case. It was also to understand what else I could use a YubiKey with. The first session taught me that a YubiKey could essentially be the keys to their digital life.

Session 3 #

I’ll be honest; I didn’t even try the commands listed in Session 2 or didn’t fully understand some of the commands listed. That is why I went through the article from Session 3; to get some understanding, to get a different perspective. After some time with this article, I found the information presented very helpful. Sadly, I left with more questions and more research I would need to do.

Session 4 #

After reviewing the content from Session 3 and other material, I decided to step back.

Do I really have to use GPG to sign my commits?

After some research, I found exactly what I needed! I found out I don’t have to. It was pretty hilarious because it was just staring me right in the face:

  1. Securing SSH Authentication with FIDO2
  2. Securing Git with SSH and FIDO security keys.

While these provide the solution, I still needed to experience a different perspective.

Session 5 #

Right when I was executing step three, I realized there might be some defaults I need to modify. In this case, that would involve the PIV components:

  • Management Key
  • PIN Code
  • PUK Code.

After some time, I decided to set everything back to defaults and set all PINs/Passwords for what components I would use.

Session 6 #

After reviewing some of the documentation, I realized that I need to understand the limits with using a YubiKey. Then I did more digging and realized that I don’t need to store anything on a YubiKey as long as I have the Private Key stored on a box to sign the commits. With this method, I configured the YubiKey with the Non-Resident key and added the Public Key to Github.

Session 7 #

Now, the fun part, testing the key with Github. In my past experiences with Git, I have always used https. An example would be the following command: git clone <REPOSITORY URL>/<YOUR-USERNAME>/<YOUR-REPOSITORY>.git. Going through this experience was the first time I took a second look at the URL. I learned that we’re instead going to use SSH through HTTPS to clone the repository; here is a template we could use for Github: git clone ssh://git@ssh.github.com:443/<YOUR-USERNAME>/<YOUR-REPOSITORY>.git.

Once I pulled the Git Repository down via SSH, I took a second look at all the documentation available from the references. Change the default format for signing commits and tags from GPG -> SSH, specify the public key, and I should be good. Through the process of signing my first commit as an initial test, the moment of pressing that YubiKey was awesome!

Summary #

Going through this process was fun and exciting. It felt like it took longer than it should have. Part of that was time I had to focus on other responsibilities/activities in my life. Another part was taking in different perspectives. The purpose of this experience, the results of this experience, was so I could sign commits related to my final project for school, and I was successful with signing a commit.

Session 1: What I Don’t Know #

Current Date: December 31st, 2024 - January 13th, 2025

Question #

What can I do with a YubiKey 5 NFC?

Answer #

The YubiKey 5 NFC is a versatile security key that supports multiple authentication protocols and can be used for various security purposes. Here are some of the key functionalities:

Two-Factor Authentication (2FA)

  • Passwordless Login: You can use your YubiKey for passwordless login on supported services, enhancing security by not relying on passwords at all.
  • Second Factor: It can act as a second factor for authentication on services like Google, Microsoft, GitHub, and many others that support FIDO U2F, FIDO2, or WebAuthn.

Supported Protocols:

  • FIDO U2F: For universal second factor authentication on websites.
  • FIDO2/WebAuthn: For passwordless and strong authentication in modern browsers.
  • Smart Card/PIV: For digital signatures, encryption, and secure login to computers and networks.
  • OpenPGP: For email encryption and signing.
  • OTP (One-Time Password): Supports both OATH-TOTP and OATH-HOTP for traditional two-factor authentication methods.

Specific Use Cases:

  • Secure Email: Use with email clients like Thunderbird for encryption and signing emails with OpenPGP.
  • SSH Authentication: Secure login to remote servers without needing passwords, using the PIV or OpenPGP functionality.
  • Physical Access: With compatible systems, it can be used for physical access control to buildings or rooms.
  • Windows Login: Secure login to Windows computers using the Smart Card/PIV functionality.
  • Cryptocurrency Wallets: Some cryptocurrency wallets support YubiKey for additional security measures.

NFC Functionality:

  • Mobile Authentication: The NFC capability allows you to authenticate on mobile devices without needing to plug in the key, enhancing convenience for smartphones and tablets.

Practical Tips:

  • Backup: Always have a backup YubiKey since if you lose your key, you might lose access to your accounts.
  • Multiple Accounts: You can register one YubiKey for multiple accounts or services, but it’s also wise to consider having different keys for different security levels or environments.

Software Management:

  • Yubico Authenticator: A tool for managing OTP credentials.
  • YubiKey Manager: For advanced configuration of your YubiKey.

To get started with your YubiKey, you would typically:

  1. Register the YubiKey with the services you use.
  2. Configure it for the specific protocols you need.
  3. Test authentication to ensure everything works as expected.

Remember, the exact usage can depend on the software or service you’re integrating with, so consulting the specific documentation for each service alongside Yubico’s guides will be beneficial.

References #

Session 2: What I Now Know #

Current Date: January 14th, 2025 - January 18th, 2025

Question #

Here is my current case; I have multiple YubiKey 5 NFC. Some of them will be backups.

I am working through an experience with this context: “The Primary goal is to allow myself to sign my commits in Github. The secondary goal is to start getting the ball rolling, get better security where applicable.”

Considering what I’ve shared, could you share a full list of what would allow me to fully utilize these devices?

Answer #

Given your goals of signing commits on GitHub and enhancing security across other applications, here’s how you can fully utilize your YubiKey 5 NFC devices:

GitHub Commit Signing:

  1. Setup GPG (GNU Privacy Guard):

    • Install GPG: On your system, ensure you have GPG installed. For Linux, macOS, or Windows (with WSL), you can use:

      bash

      sudo apt-get install gnupg  # For Debian/Ubuntu
brew install gnupg          # For macOS with Homebrew

    • Generate a Key: Use your YubiKey to generate a new key or import an existing one. Here’s a basic command to generate:

      gpg --full-generate-key

      When prompted, select RSA and RSA (default), then choose a key size like 4096 bits. Use the YubiKey for both encryption and signing.

    • Configure YubiKey for GPG: Use gpg –card-edit to manage your YubiKey settings:

      gpg --card-edit

      Here, you’ll set your name, admin PIN, etc., on the key.

    • Export Public Key: After setting up, export your public key to share or add to GitHub:

      gpg --export --armor [your-key-id] > mykey.asc

      Then, add this public key to your GitHub account under “SSH and GPG keys”.

    • Sign Commits: Configure Git to use your GPG key:

      git config --global user.signingkey [your-key-id]
git config --global commit.gpgsign true

Expanding Security Usage:

  1. Two-Factor Authentication (2FA):
    • GitHub: Register your YubiKey for 2FA in GitHub’s security settings.
    • Other Services: Use it for 2FA with services like Google, Dropbox, or any service supporting FIDO U2F, FIDO2, or TOTP.
  2. SSH Authentication:

    • Generate SSH Key on YubiKey: Use gpg –export-ssh-key [your-key-id] to get your SSH public key from your GPG key.

    • Add to GitHub: Add this SSH public key to GitHub for SSH authentication to repositories.

    • Configure SSH: Update your ~/.ssh/config to use the YubiKey for SSH:

      Host github.com
  IdentityFile ~/.gnupg/sshcontrol
  3. Email Encryption/Signing:
    • Email Clients: Use your GPG key with email clients like Thunderbird or Outlook with plugins like Enigmail for Thunderbird or GPG4Win for Outlook.
  4. Password Management:
    • LastPass or Bitwarden: Integrate with password managers that support YubiKey for enhanced security.
  5. Windows Login:
    • Smart Card Login: Configure your Windows machine to allow login via your YubiKey using the Smart Card/PIV functionality.
  6. Backup and Management:

    • Backup Keys: Since you have multiple YubiKeys, clone your key settings to each backup key. Use gpg –card-edit and admin mode to manage:

      admin
generate

    • YubiKey Manager: Use this tool to manage different configurations on your keys.

  7. Mobile Authentication:
    • NFC: Use NFC on your mobile devices for quick authentication on apps that support it.

Additional Considerations:

  • PIN Protection: Set a strong PIN for your YubiKey to protect against unauthorized use.
  • Regular Updates: Keep your software and firmware updated for security.
  • Documentation: Keep track of which key is used for what, especially if you’re using different keys for different purposes.

By implementing these measures, you’ll significantly enhance your security posture while achieving your primary and secondary goals with the YubiKey 5 NFC. Remember, security is an ongoing process, so regularly review and update your security practices.

References #

  1. https://www.yubico.com/support/knowledge-base/categories/articles/use-yubikey-openpgp/#generatelocal

Session 3: Richard Rzetterberg’s Perspective #

Current Date: January 18th, 2025 - January 20th, 2025

In this article we will setup NixOS to use GPG-keys for SSH authentication, while storing the keys securely on a Yubikey.

Anatomy of a GPG Key #

GPG-keys are more like a data structure with different components than a “key”. In essence a GPG key consists of 4 parts:

  1. Primary key pair: Also called master key
  2. Primary identity: Also just called user identity or uid
  3. Extra identities: Extra user identities linked to the primary key pair
  4. Subkey pairs: Extra keys derived from the primary key pair

Sub-key Pairs #

Subkey pairs are basically normal key pairs that has a signature that associates them to the primary key pair. When a subkey pair is created, the primary private key is used to create this signature.

The most powerful action is called Certify, which allows a key pair to create subkey pairs from itself. A subkey pair is just a key pair but with a signature that associates it to another key pair. The primary key pair will therefor always have the Certify capability, so that it can create subkey pairs.

There are 3 other actions a key pair can perform:

Sign: Signing files, emails, etc.

Encrypt: Encrypting files, emails, etc.

Authenticate: Authenticating against external services, such as SSH

Our Goal #

  • Create a GPG key
    • With a primary keypair that can only Certify
    • With a single user identity
    • With a subkey pair that can only Sign
    • With a subkey pair that can only Encrypt
    • With a subkey pair that can only Authenticate
  • Backup the primary key pair and it’s subkey pairs offline on a USB-stick
  • Configure our Yubikey
  • Move the 3 subkey pairs to our Yubikey
  • Configure NixOS to use GPG and our Yubikey for SSH authentication:

Creating a New Key #

By the way, when gpg list keys, it uses the following terminology:

sec: SECret key

ssb: Secret SuBkey

pub: PUBlic key

sub: public SUBkey

Installing and Configuring Dependencies #

ykpersonalize -V
USB error: Access denied (insufficient permissions)

The reason we are seeing this error is because the device manager udev doesn’t allow access to USB-devices unless there is a rule for it.

GPG/SSH Agent #

Basically gpg-agent can emulate ssh-agent this would let you use normal SSH keys and GPG keys.

References #

  1. https://rzetterberg.github.io/yubikey-gpg-nixos.html

Session 4: Yubico Developer Documentation #

Current Date: January 22nd, 2025 - January 23rd, 2025

Question #

What does the following command do? ssh-keygen -t ed25519-sk -O resident -O application=ssh:Description -C "Comment"

Answer #

The command ssh-keygen -t ed25519-sk -O resident -O application=ssh:Description -C “Comment” generates an SSH key pair with the following specifications:

-t ed25519-sk: Specifies the type of key to create. Here, ed25519-sk refers to an Ed25519 key with FIDO/U2F security key support. This means the key will be stored on a security key device (like a YubiKey or similar hardware security token) rather than on the local machine.

-O resident: This option makes the key a "resident key". A resident key can be used without needing to provide the key's identifier each time; the key is discoverable and can be listed by the security key. This is particularly useful for keys stored on FIDO2 devices where the key can be used without specifying its handle or relying on the specific slot on the device.

-O application=ssh:Description: This option sets an application string for the key, which is used to further identify or classify the key's purpose on the security key. Here, "Description" would be replaced with some text that describes what the key is for. This helps in managing multiple keys on a single security device by giving context or grouping keys by their intended use.

-C "Comment": Adds a comment to the key. This comment can be any text and is useful for identifying the key's purpose or owner when viewing the key or in key management operations. In this case, "Comment" would be replaced with whatever specific comment you want to add.

When you run this command:

1. It will prompt for a passphrase to secure the private key unless you specify -N "" for no passphrase.
2. It will generate a private key file named id_ed25519_sk (by default) in the ~/.ssh directory and a corresponding public key file named id_ed25519_sk.pub.
3. The key will be stored on your security key device in a way that it can be used directly by SSH without needing to input the key handle each time.

This setup enhances security by using hardware-based key storage, making key theft from the computer more difficult, and the use of resident and application options aids in key management on devices that might hold multiple keys.

References #

  1. SSH Authentication with YubiKeys
  2. Drduh YubiKey-Guide Github Repository

Session 5 - Reset the Key’s! #

Current Date: January 25th, 2025 - January 28th, 2025

For this session, I created documentation to setup the foundation for using this YubiKey:

  1. Recommended Changes
  2. Factory Reset Components

Session 6 - There are limitations to the storage?! #

Current Date: January 29th, 2025

YubiKey 5 Series firmware 5.7+ #

  • FIDO2 - the YubiKey 5 can hold up to 100 discoverable credentials (AKA hardware-bound passkeys) in its FIDO2 application.
  • FIDO U2F - similar to Yubico OTP, the FIDO U2F application can be registered with an unlimited number of services.
  • PIV - the YubiKey 5’s PIV (smart card) application has 4 usable slots per the PIV specification, each serving a specific purpose (authentication, digital signature, key management, and card authentication - click here for further information). In a Microsoft Windows environment and used in conjunction with the YubiKey Smart Card Minidriver, the number of usable certificates expands to approximately 12 (dependent upon many factors including algorithm used as well as various Certification Authority settings).
  • OATH-TOTP - the YubiKey 5’s OATH application can hold up to 64 OATH-TOTP credentials (AKA authenticator codes).
  • **OTP ** - this application can hold two credentials. However, Yubico OTP, one of the most popular kinds of credentials to put in this app, can be registered with an unlimited number of services.
    • The OTP application comes with:
      • Yubico OTP
      • Challenge-Response
      • Static Password
      • OATH-HOTP
  • OpenPGP - the YubiKey 5’s OpenPGP application can hold up to 3 subkeys (signature, encryption, authentication) linked to a single OpenPGP identity.

YubiKeys 5 Series with firmware 5.0-5.6 #

  • FIDO2 - the YubiKey 5 can hold up to 25 discoverable credentials (AKA hardware-bound passkeys) in its FIDO2 application.
  • FIDO U2F - similar to Yubico OTP, the FIDO U2F application can be registered with an unlimited number of services.
  • PIV - the YubiKey 5’s PIV (smart card) application has 4 usable slots per the PIV specification, each serving a specific purpose (authentication, digital signature, key management, and card authentication - click here for further information). In a Microsoft Windows environment and used in conjunction with the YubiKey Smart Card Minidriver, the number of usable certificates expands to approximately 12 (dependent upon many factors including algorithm used as well as various Certification Authority settings).
  • OATH-TOTP - the YubiKey 5’s OATH application can hold up to 32 OATH-TOTP credentials (AKA authenticator codes).
  • OTP - this application can hold two credentials. However, Yubico OTP, one of the most popular kinds of credentials to put in this app, can be registered with an unlimited number of services.
    • The OTP application comes with:
      • Yubico OTP
      • Challenge-Response
      • Static Password
      • OATH-HOTP
  • OpenPGP - the YubiKey 5’s OpenPGP application can hold up to 3 subkeys (signature, encryption, authentication) linked to a single OpenPGP identity.

References #

  1. How many accounts can I register my YubiKey with?
  2. Securing SSH Authentication with FIDO2
  3. Securing Git with SSH and FIDO security keys

Session 7 - Lets’ Finish This! #

Current Date: January 30th, 2025

git clone ssh://git@ssh.github.com:443/YOUR-USERNAME/YOUR-REPOSITORY.git

Source: Second Reference.

References #

  1. Testing your SSH connection.
  2. Enabling SSH connections over HTTPS
  3. Telling Git about your SSH key
  4. Signing commits