From d97e51eadc880b79cc46ab6b41057775c1552c48 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 12 Feb 2023 16:27:35 +0100 Subject: [PATCH 01/17] pages/yubikey: update What is a YubiKey section Added more use-cases than OTP to this section to give an overview on the usual capabilities of modern YubiKeys like from the 5-series. --- modules/ROOT/pages/using-yubikeys.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index a09a92c..e4cbead 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -11,11 +11,11 @@ The Fedora docs team This page has not been thoroughly reviewed for technical accuracy for quite some time. This means any information on this page may be outdated or inaccurate. Reviews for technical accuracy are greatly appreciated. If you want to help, either edit it or open a ticket using the appropriate button on the right side below the banner. ==== -== What is a yubikey? +== What is a YubiKey? -A Yubikey is a small USB based device that generates one time passwords (OTPs). They are created and sold via a company called http://yubico.com/[Yubico]. +A YubiKey is a small USB and NFC based device, a so called https://developers.yubico.com/Developer_Program/Guides/YubiKey_Hardware.html[hardware security token], with modules for many security related use-cases. It generates one time passwords (OTPs), stores private keys and in general implements different authentication protocols. They are created and sold via a company called http://yubico.com/[Yubico]. -For more information about yubikey features, see their https://yubico.com/products/[product page]. +For more information about YubiKey features, see their https://yubico.com/products/[product page]. == How do I get a yubikey? From 26ca6635f077d948f2efe90290eeac9d9fc81faa Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 12 Feb 2023 16:29:03 +0100 Subject: [PATCH 02/17] pages/yubikey: add a section on backup keys Due to the nature of hardware security tokens it is important to consider backup keys right from the start, so added a section on that topic. --- modules/ROOT/pages/using-yubikeys.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index e4cbead..e52fa0c 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -21,11 +21,11 @@ For more information about YubiKey features, see their https://yubico.com/produc You can purchase a yubikey from http://store.yubico.com/[Yubico's website]. -== Using a Yubikey to authenticate to a machine running Fedora +== Consider a backup YubiKey -There are two main ways to configure the yubikey PAM module to authenticate users, via the YubiCloud, or using challenge-response. The YubiCloud is the standard method, and involves leveraging Yubico's cloud to validate your yubikey. While this guide will cover the YubiCloud method, it is worth looking into challenge-response if you do not trust the YubiCloud, or will not always have an internet connection. +As soon as you start working with security tokens you have to account for the potential to lock yourself out of accounts tied to these tokens. As hardware security tokens are unique and designed to be extremely hard to copy you can't just make a backup of it like you can with software vaults like Keepass or AndOTP. Because of this all registrations you do with your primary key you should immediately do with a second backup key that you store in a secure location like a safe or at least always leave at home. -This part of this document assumes you have a machine running Fedora and you have root access over SSH or through the console. TODO: Add a little something about gdm / kdm based logins below. +In practice this means to register both hardware tokens with your linux and web accounts, generate private keys twice and configure both public keys at e.g. github. First, we need to install the required software. Since Fedora 18 you can install the pam_yubico package by running[source,] From a7c4670ec556b882c21efc18f64a80d253688e5c Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 12 Feb 2023 16:32:48 +0100 Subject: [PATCH 03/17] pages/yubikey: rework the local auth section Changed the structure and content of the section to reflect more modern tooling available in recent Fedora Linux distributions. Simplified overall structure and added challenge-response configuration. Removed the more complicated authfile option as it is an option for more advanced use-cases but not necessary for a basic setup. More advanced users may refer to the pam_yubico man page. Added a warning about locking yourself out when using required configuration. --- modules/ROOT/pages/using-yubikeys.adoc | 175 +++++++++++++++---------- 1 file changed, 104 insertions(+), 71 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index e52fa0c..206886c 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -27,121 +27,154 @@ As soon as you start working with security tokens you have to account for the po In practice this means to register both hardware tokens with your linux and web accounts, generate private keys twice and configure both public keys at e.g. github. -First, we need to install the required software. Since Fedora 18 you can install the pam_yubico package by running[source,] +== Storage limitations + +For some features private keys and other secrets are stored on the YubiKey. Each feature has it's own storage space and hence https://support.yubico.com/hc/en-us/articles/360013790319-How-many-accounts-can-I-register-my-YubiKey-with-[maximum number of credential slots]: + +- OTP - Unlimited, as only one secret per key is required +- FIDO U2F - Unlimited, as only one secret per key is required +- FIDO2 - 25 credentials +- OATH - 32 credentials +- PIV - 24 x509 certificates and their respective private keys +- OpenPGP - 3 keys; one for encryption, signing and authentication each + +== Using a YubiKey to authenticate to a machine running Fedora + +Local system authentication uses https://www.redhat.com/sysadmin/pluggable-authentication-modules-pam[Pluggable Authentication Modules (PAM)]. There are two ways to configure the YubiKey PAM module to authenticate users. Either via the YubiCloud or using challenge-response. The YubiCloud is the standard method but depends on Yubico's cloud to validate your OTPs and hence requires constant internet access. + +The setup is as follows: install the PAM module, register a YubiKey with your user account, create base configuration for either of the two authentication options and then choose the PAM configuration you want to use the YubiKey. + +Install the PAM yubico module from the official repositories: [source, bash] […]$ sudo dnf install pam_yubico +Register a currently connected YubiKey with your user account with -Next, we need to configure PAM (Pluggable Authentication Modules, the main Linux authentication mechanism) to accept a Yubikey as a means of authentication. For our example setup, we will first accept a Yubikey OTP as 'sufficient'. This means that a Yubikey alone is enough to authenticate a -user. - -Open /etc/pam.d/login with your editor of choice. This guide will use nano. [source, bash] -[…]$ sudo nano /etc/pam.d/login +[…]$ ykpamcfg -2 -v -Find the line that reads "auth substack system-auth". Above that, insert the following: +Or for any other system user using sudo with + +[source, bash] +[…]$ sudo -u someuser ykpamcfg -2 -v + +Create two base configuration files in /etc/pam.d. yubikey-required and yubikey-sufficient. + +For YubiCloud use the following: + +[source] +#%PAM-1.0 +auth required pam_yubico.so id=[Your API Client ID] key=[Your API Client Key] + +[source] +#%PAM-1.0 +auth sufficient pam_yubico.so id=[Your API Client ID] key=[Your API Client Key] + +[CAUTION] ==== -auth sufficient pam_yubico.so debug id=1 authfile=/etc/yubikeys +Note that the key is optional but without it there is no TLS verification which makes this susceptible to MitM attacks by default. Obtain a key at https://upgrade.yubico.com/getapikey[Yubico]. ==== -Do not worry about id and authfile right now, we will configure them later. Mind that the ''debug'' part is purely so we can see some output, and can be removed after the yubikey is setup. - -Now we have a PAM configuration that will accept Yubikey as a means of user authentication. Next we will tell it which user is authenticated by which yubikey using the "authfile" option. - -The ''authfile'' option makes it easy to centrally map yubikeys to users. More information about "authfile" can be found at the following link under https://developers.yubico.com/yubico-pam/["Authorization Mapping Files"]. - -Open /etc/yubikeys in an editor. -[source, bash] -[…]$ sudo nano /etc/yubikeys - - -You will now need to add mappings in the format of :. The easiest way to find the token ID is to remove the trailing 32 characters of an OTP (the characters spit out when a yubikey is tapped). Here is what an authfile might look like: ----- -root:cccccccccccc -harry:cclcclcclccl ----- - -This file designates that the "root" user will be paired with the yubikey with the "cccccccccccc", and the "harry" user will be authenticated with the "cclcclcclccl" yubikey. You may add multiple yubikeys to a user by separating the token IDs with a colon. For example, here we will allow the "root" yubikey to also authenticate "harry": ----- -root:cccccccccccc -harry:cclcclcclccl:cccccccccccc ----- - -When you have finished editing the file, make sure that its permissions are set to the least permissive value. -[source, bash] -[…]$ sudo chmod 0400 /etc/yubikeys - - -Alternatively, you can allow your users to make their own mappings. Just remove the ''authfile'' option to pam_yubico.so. Tell your users to create a .yubico directory in their home directory and make a mapping file in it called authorized_yubikeys. This and the authfile option are mutually exclusive. - -So, let's try it out. Let's start with a console login, because then we can see -the nice debug output when we log in. - [NOTE] ==== If you have SELinux on the enforcing mode (the default mode), you should flip on the allow_ypbind boolean first, because pam_yubico needs to be able to connect to Yubico's online authentication. servers. + [source, bash] […]$ sudo setsebool -P allow_ypbind=1 Also, in order to allow sshd to access /root/.yubico/authorized_yubikeys, you should change its context: + [source, bash] […]$ chcon -R system_u:object_r:ssh_home_t:s0 /root/.yubico ==== +For challenge-response use the following: -With this done, you should be all ready to go! The next time you open a console (local, not ssh session) and attempt to login you should be prompted `Yubikey for '':`. Tap your yubikey to input an OTP and, hopefully, you will be logged in successfully. +[source] +#%PAM-1.0 +auth required pam_yubico.so mode=challenge-response -Once you have verified things are working, feel free to remove the "debug" parameter from `/etc/pam.d/login` so that you won't get the debug logging in your console. +[source] +#%PAM-1.0 +auth sufficient pam_yubico.so mode=challenge-response -== Additional Configuration -There are a number of common things people might want to configure their yubikey to do. In this section we will cover those. +[NOTE] +==== +You may add the debug option at the end of these lines right after the mode option to get troubleshooting information in journald. +==== -=== Requiring both yubikey and password +Next configure PAM to accept a YubiKey as a means of authentication. There are many options in /etc/pam.d to modify and add a YubiKey, but the most common use-cases are: -In the previous section we configured the yubikey to be a replacement for users' passwords. However, there are times in which you may want both a yubikey and a password to be required. To accomplish this, we change the `pam_yubico.so` lines in `/etc/pam.d/*` to read 'required' instead of 'sufficient', like below: ----- -auth required pam_yubico.so id=1 authfile=/etc/yubikeys ----- +- /etc/pam.d/login +- /etc/pam.d/gdm +- /etc/pam.d/sudo +- /etc/pam.d/sshd -Now you'll be queried for both Yubikey OTP and your normal password at login! +In a PAM configuration file if using yubikey-sufficient add an include line before or if using yubikey-required add it after a line that reads "auth substack system-auth" or "auth include system-auth". An include of yubikey-sufficient looks like this: -=== Using a yubikey for more than login +[source] +auth include yubikey-sufficient -We have configured the yubikey to be used in regular logins, but many users would like to use their yubikeys for tasks such as ssh and root elevation. In order to accomplish this, we must copy the pam_yubico.so line we've written into the other PAM modules we wish to integrate with. +The following example sets a YubiKey OTP as 'sufficient' factor for terminal login. This means that a YubiKey alone is enough to authenticate a user when logging in on a terminal. -As a reminder, here is our line we've been using: ----- -auth sufficient pam_yubico.so id=1 authfile=/etc/yubikeys ----- +Open /etc/pam.d/login with your editor of choice. Find the line that reads "auth substack system-auth". Above that, insert the following: -To allow using a yubikey to authenticate with sudo, add our line to the file `/etc/pam.d/sudo`. +[source] +auth include yubikey-sufficient -To allow using a yubikey to authenticate with sshd, add our line to the file `/etc/pam.d/sshd`. +The result looks similar to this: -== Customizing a Yubikey with Fedora +[source] +#%PAM-1.0 +auth substack system-auth +auth include postlogin +account required pam_nologin.so +account include system-auth +password include system-auth +# pam_selinux.so close should be the first session rule +session required pam_selinux.so close +session required pam_loginuid.so +# pam_selinux.so open should only be followed by sessions to be executed in the user context +session required pam_selinux.so open +session required pam_namespace.so +session optional pam_keyinit.so force revoke +session include system-auth +session include postlogin +-session optional pam_ck_connector.so -A Yubikey generates OTPs by encrypting an internally generated string (containing a counter, among others) with an AES key. The AES key is stored on the device, together with an identifier and a counter. The complete picture of what is on the key is painted in detail in the https://www.yubico.com/wp-content/uploads/2015/03/YubiKeyManual_v3.4.pdf[Yubikey manual]. +Next time you open a console (local, not ssh session) and attempt to login you should be prompted `YubiKey for '':`. Tap your YubiKey to input an OTP and you will be logged without entering a password. + +[CAUTION] +==== +When using the yubikey-required option make sure to test this thoroughly in another session without closing your current one to mitigate locking yourself out of the system. +==== + +To add a YubiKey to more than terminal login, like local sshd servers, sudo or GDM login, add the respective auth include to one of the other configuration files in /etc/pam.d. + +== Customizing a YubiKey with Fedora + +A YubiKey comes pre-configured for Yubico OTP, but apart from that it uses default PINs for every other feature which you'll most likely want to change before use. There is software for customizing the YubiKey in the official repositories. + +There are essentially two tools to use together with their respective GUI variants. 'yubikey-manager' and 'ykpersonalize'. The former is newer but supports less options than the latter. For all available options install both. -Before we start, we need to install the appropriate software to customize Yubikeys. In the following guide we will use the older and more powerful commandline tool 'ykpersonalize': [source, bash] -[…]$ su -c "yum install ykpers" +[…]$ sudo dnf install ykpers There is a gui for this command: + [source, bash] -[…]$ su -c "yum install yubikey-personalization-gui" +[…]$ sudo dnf install yubikey-personalization-gui There is a more recent, simpler tool, ykman: + [source, bash] -[…]$ su -c "yum install yubikey-manager" +[…]$ sudo dnf install yubikey-manager + +YubiKey manager also has a gui: -Yubikey manager also has a gui: [source, bash] -[…]$ su -c "yum install yubikey-manager-qt" - -Yubikey-manager has all the necessary commands to manage your yubikey, and the gui is easy to use and self explanatory. - -The following instructions are for the older tool, ykpersonalize. +[…]$ sudo dnf install yubikey-manager-gui === Writing a new static password to the second slot of the key From 241c0afc5b9476917e02205c9e875388a78aa05a Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 12 Feb 2023 16:37:35 +0100 Subject: [PATCH 04/17] pages/yubikey: add a simple otp slot 2 example --- modules/ROOT/pages/using-yubikeys.adoc | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 206886c..d22133e 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -178,15 +178,19 @@ YubiKey manager also has a gui: === Writing a new static password to the second slot of the key -Newer Yubikeys (Yubikey 2+) have the ability to store two separate configurations. The first is generally used for OTPs, the second for a strong, static password. If the button is pressed shortly, something up to 1.5 seconds, the first configuration is triggered. If the button is pressed -longer, in the range of 2.5 to 5 seconds, the second configuration is triggered. +Newer YubiKeys (YubiKey 2+) have the ability to store two separate configurations. The first is generally used for OTPs, the second for a strong, static password. If the button is pressed shortly, something up to 1.5 seconds, the first configuration is triggered. If the button is pressed longer, in the range of 2.5 to 5 seconds, the second configuration is triggered. -For this first example we are going to write a new static key to the second configuration of a Yubikey 2. +Write a static key using ykman otp static. [source, bash] -[…]$ sudo ykpersonalize -oappend-cr -a123456deadcafebeef65432112345678 -2 -o-man-update +[…]$ ykman otp static 2 cbdefghijklnrtuv -This writes a static key to the Yubikey based on the 32-byte AES key I gave with the -a option. The -2 option tells it to write to the second configuration. The other two options are a matter of personal taste. The append-cr option sends a carriage return as the last character of the key. That way I do not have to press myself. The -man-update option disables easy updating of the static key in the Yubikey. Enabling this will allow for altering the static password without the use of ykpersonalize. +A more elaborate example: write a new static key to the second configuration slot using a specific AES key. + +[source, bash] +[…]$ ykpersonalize -oappend-cr -a123456deadcafebeef65432112345678 -2 -o-man-update + +This writes a static key to the YubiKey based on the 32-byte AES key specified with the -a option. The -2 option sets the second slot as target. The other two options are a matter of personal taste. The append-cr option sends a carriage return as the last character of the key. That way I do not have to press myself. The -man-update option disables easy updating of the static key in the YubiKey. Enabling this will allow for altering the static password without the use of ykpersonalize. === Writing a new AES key to the first slot of the key From b04799e7e919fee52cc40655d5cd82601302536d Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 12 Feb 2023 16:38:28 +0100 Subject: [PATCH 05/17] pages/yubikey: add setup sections for other features --- modules/ROOT/pages/using-yubikeys.adoc | 65 +++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index d22133e..18edfff 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -231,7 +231,70 @@ which is a modified representation of hexadecimal characters that uses only 'saf === Uploading the generated AES key to Yubico -If you want to customize your Yubikey's AES key but still want to use it to authenticate through Yubico's servers, you can upload the key through https://upgrade.yubico.com/getapikey/. You will need to enter your email address and Yubikey's OTP. +If you want to customize your YubiKey's AES key but still want to use it to authenticate through Yubico's servers, you can upload the key through https://upgrade.yubico.com/getapikey/. You will need to enter your email address and YubiKey's OTP. + +=== Update the PINs of the PIV module + +The https://www.yubico.com/authentication-standards/smart-card/[Personal Identitiy Verification (PIV)] module stores private keys and corresponding certificate files for purposes such as encryption, authentication and signatures. If your YubiKey supports this you want to change the PIN and PUK as well as the Management Key. + +Set the PIN. + +[source, bash] +[…]$ ykman piv access change-pin +Enter the current PIN: 123456 +Enter the new PIN: ******** +Repeat for confirmation: ******** +New PIN set. + +Set the PUK. + +[source, bash] +[…]$ ykman piv access change-puk +Enter the current PUK: 12345678 +Enter the new PUK: ******** +Repeat for confirmation: ******** +New PUK set. + +Update the Management Key. + +[source, bash] +[…]$ ykman piv access change-management-key --generate --protect +Enter the current management key [blank to use default key]: +Enter PIN: ******** + +You can now safely use the PIV module to generate private keys and store certificates. + +=== Change the PIN of the FIDO2 module + +https://www.yubico.com/authentication-standards/fido2/[FIDO2] is an open authentication standard and encompasses sub-standards and protocols to either provide two-factor or even passwordless authentication methods. + +One interesting use case of the FIDO module to note is storing OpenSSH public-key identities, which modern OpenSSH agents can pick up right away and use. This makes ssh keys quite portable. + +If your key supports FIDO change it's pin with ykman fido access like this: + +[source, bash] +[…]$ ykman piv access change-pin +Enter the current PIN: 123456 +Enter the new PIN: ******** +Repeat for confirmation: ******** +New PIN set. + +=== Configure a password for OATH + +The OATH feature provides TOTP and HOTP authentication protocols. It can be protected with a passphrase to access and generate OTP codes. This is different from the Yubico OTP feature, which uses a single stored secret on the YubiKey for challenge-response. + +Change the OATH password with: + +[source, bash] +[…]$ ykman oath access change +Enter the new password: +Repeat for confirmation: + +Configure your device to remember this password so you don't have to re-enter it anymore. + +[source, bash] +[…]$ ykman oath access remember + == Using the Yubikey to authenticate to websites From 05a7579f46c049e583ed762562e02c0defd64956 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 12 Feb 2023 16:39:07 +0100 Subject: [PATCH 06/17] pages/yubikey: add section on OpenSSH client auth --- modules/ROOT/pages/using-yubikeys.adoc | 32 ++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 18edfff..0859bb4 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -295,6 +295,38 @@ Configure your device to remember this password so you don't have to re-enter it [source, bash] […]$ ykman oath access remember +== Using the YubiKey to authenticate against OpenSSH servers + +The PIV module can store OpenSSH private keys. The FIDO module can store the corresponding public key. Using only PIV requires export of the public key component onto every new host. In addition with the FIDO module this step is not necessary, if the OpenSSH agent has smart card support. + +Create an ED25519 private key inside the PIV module, requiring pin entry upon use and always require a touch of the YubiKey button: + +[source, bash] +[…]$ ykman piv keys generate --algorithm ED25519 --pin-policy ONCE --touch-policy ALWAYS 9a public.pem +Enter PIN: ******** + +The slot 9a on the key is dedicated to authentication. There are https://docs.yubico.com/yesdk/users-manual/application-piv/slots.html[more slots] for features like encryption or signing. + +Create a certificate in this same slot for the PIV/PKCS#11 library: + +[source, bash] +[…]$ ykman piv certificates generate --subject "CN=OpenSSH" --hash-algorithm SHA384 9a pubkey.pem +Enter PIN: ******** +Touch your YubiKey… + +Generate a public key on every host you intend to use the private key, so an OpenSSH agent may discover it: + +[source, bash] +[…]$ ssh-keygen -t ed25519-sk + +Generate the public key and store it's identity in the FIDO2 module to make the private-public key-pair portable: + +[source, bash] +[…]$ ssh-keygen -t ed25519-sk -O resident -O application=ssh:fedora -O verify-required + +[NOTE] +So called resident keys require that the private key is protected by a PIN. + == Using the Yubikey to authenticate to websites From a6b5d2490d62431d4ef1d6bcfabdc25c4ad89112 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 12 Feb 2023 16:39:33 +0100 Subject: [PATCH 07/17] pages/yubikey: add OATH-TOTP to web auth section --- modules/ROOT/pages/using-yubikeys.adoc | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 0859bb4..8227799 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -327,7 +327,23 @@ Generate the public key and store it's identity in the FIDO2 module to make the [NOTE] So called resident keys require that the private key is protected by a PIN. +== Using the YubiKey to authenticate to websites -== Using the Yubikey to authenticate to websites +As of 2019, there is work in place to attempt to standardize using a YubiKey on the web. The new standard is called WebAuthn, and you can learn more about it here: https://www.yubico.com/solutions/webauthn/. For now, the easiest way to see which platforms support the YubiKey is by browsing https://www.yubico.com/works-with-yubikey/catalog/[yubico's catalog]. -As of 2019, there is work in place to attempt to standardize using a yubikey on the web. The new standard is called WebAuthn, and you can learn more about it here: https://www.yubico.com/solutions/webauthn/. For now, the easiest way to see which platforms support the yubikey is by browsing https://www.yubico.com/works-with-yubikey/catalog/[yubico's catalog]. \ No newline at end of file +As an alternative to Yubico OTP or WebAuthn, which both don't require storage of credentials on the YubiKey by default, you may also use plain old TOTP like employed in most websites today. There are desktop and at least android apps to work with this conveniently. You may store up to 32 TOTP credentials on a YubiKey 5. + +Install the desktop application from the official repositories: + +[source, bash] +[…]$ sudo dnf install -y yubioath-desktop + +Add an TOTP account with ykman like this: + +[source, bash] +[…]$ ykman oath accounts add google + +Retrieve a TOTP code like this: + +[source, bash] +[…]$ ykman oath accounts code google From 93f06ff42224f4651c060c9b33b7a11fd8f8889b Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 12 Feb 2023 16:40:00 +0100 Subject: [PATCH 08/17] pages/yubikey: unify use of YubiKey spelling --- modules/ROOT/pages/using-yubikeys.adoc | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 8227799..28794e4 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -1,7 +1,7 @@ -= Using Yubikeys with Fedora += Using YubiKeys with Fedora The Fedora docs team :revnumber: unknown -:revdate: 2022-06-16 +:revdate: 2023-02-12 :category: Using // :tags: From Source @@ -17,9 +17,9 @@ A YubiKey is a small USB and NFC based device, a so called https://developers.yu For more information about YubiKey features, see their https://yubico.com/products/[product page]. -== How do I get a yubikey? +== How do I get a YubiKey? -You can purchase a yubikey from http://store.yubico.com/[Yubico's website]. +You can purchase a YubiKey from http://store.yubico.com/[Yubico's website]. == Consider a backup YubiKey @@ -176,7 +176,7 @@ YubiKey manager also has a gui: [source, bash] […]$ sudo dnf install yubikey-manager-gui -=== Writing a new static password to the second slot of the key +=== Writing a new static password to the second slot of the key Newer YubiKeys (YubiKey 2+) have the ability to store two separate configurations. The first is generally used for OTPs, the second for a strong, static password. If the button is pressed shortly, something up to 1.5 seconds, the first configuration is triggered. If the button is pressed longer, in the range of 2.5 to 5 seconds, the second configuration is triggered. @@ -197,9 +197,9 @@ This writes a static key to the YubiKey based on the 32-byte AES key specified w If we want to write a new configuration to the first slot of the key, we need to specify some more options. If you want to be able to upload you key to Yubico, in order to authenticate against their servers, remember what the values are that you use below. You will need them later on. [source, bash] -[…]$ sudo ykpersonalize -1 -ofixed=vvhhhrhkhgidic -ouid=deadbeefcafe -a123456deadcfaebeef65432112345678 -oappend-cr +[…]$ ykpersonalize -1 -ofixed=vvhhhrhkhgidic -ouid=deadbeefcafe -a123456deadcfaebeef65432112345678 -oappend-cr -The -1 option tells ykpersonalize to use the first configuration. The fixed option specifies the public ID of the Yubikey. This is referred to as the 'prefix' later on, when we go uploading it. The value you use here has to start with 'ff' in hex or 'vv' in modhex (xref:#_what_is_modhex[see below]). Yubico enforces this when you try to upload your key to their servers. The value for the fixed option can be up to 16 characters in length. +The -1 option tells ykpersonalize to use the first configuration. The fixed option specifies the public ID of the YubiKey. This is referred to as the 'prefix' later on, when we go uploading it. The value you use here has to start with 'ff' in hex or 'vv' in modhex (xref:#_what_is_modhex[see below]). Yubico enforces this when you try to upload your key to their servers. The value for the fixed option can be up to 16 characters in length. As part of the OTP, you can specify an internal identifier for your key. This is what the uid option does. The value is in plain hex, not modhex and ''exactly'' 12 character long. @@ -226,8 +226,7 @@ After pressing 'y', I am able to generate OTPs with my new key! ==== What is modhex? -When plugged in, the operating system treats the Yubikey as a USB keyboard. USB keyboards send scancodes to the operating system, which the operating system then interprets as keystrokes. The Yubikey has to make sure no ambiguity arises: there are many different kinds of keyboard layouts and the scancodes have to be interpreted as the same character on machines using every random keyboard layout out there. To fix this, the people of Yubico have created 'modhex', -which is a modified representation of hexadecimal characters that uses only 'safe' characters. 'Safe' characters are basically characters which have the same scancode on all keyboard layouts. +When plugged in, the operating system treats the YubiKey as a USB keyboard. USB keyboards send scancodes to the operating system, which the operating system then interprets as keystrokes. The YubiKey has to make sure no ambiguity arises: there are many different kinds of keyboard layouts and the scancodes have to be interpreted as the same character on machines using every random keyboard layout out there. To fix this, the people of Yubico have created 'modhex', which is a modified representation of hexadecimal characters that uses only 'safe' characters. 'Safe' characters are basically characters which have the same scancode on all keyboard layouts. === Uploading the generated AES key to Yubico From 4274f89f0029246a980ae70cd89dd1cc75f5aac3 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Fri, 17 Feb 2023 20:14:38 +0100 Subject: [PATCH 09/17] pages/yubikey: remove note on setting secontext The access to the ~/.yubico directory is done using the PAM module, not sshd directly. PAM sets the context of that directory to auth_home_t which PAM is allowed to access. No need to set the context to ssh_home_t. Apart from that using chcon is a volatile operation and not intended for persistent changes which was the intent of the note though. The label would be reset in a system recovery scenario. --- modules/ROOT/pages/using-yubikeys.adoc | 5 ----- 1 file changed, 5 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 28794e4..4c7c36e 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -82,11 +82,6 @@ If you have SELinux on the enforcing mode (the default mode), you should flip on [source, bash] […]$ sudo setsebool -P allow_ypbind=1 - -Also, in order to allow sshd to access /root/.yubico/authorized_yubikeys, you should change its context: - -[source, bash] -[…]$ chcon -R system_u:object_r:ssh_home_t:s0 /root/.yubico ==== For challenge-response use the following: From da454cc861a96468211e9852bb54f999bb3ac0e1 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sat, 18 Feb 2023 10:48:26 +0100 Subject: [PATCH 10/17] pages/yubikey: reformat flags of ykpersonalize The man page of ykpersonalize uses a confusing format for providing option flags. After tests although not documented in the man page it is also possible to use an alternative format using spaces between option flag and value. Also to note: the negative form of an option flag uses a '-' symbol right in front of the value. Also the slot selector -1 or -2 has to be supplied before any option flag. --- modules/ROOT/pages/using-yubikeys.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 4c7c36e..2f97fd0 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -183,7 +183,7 @@ Write a static key using ykman otp static. A more elaborate example: write a new static key to the second configuration slot using a specific AES key. [source, bash] -[…]$ ykpersonalize -oappend-cr -a123456deadcafebeef65432112345678 -2 -o-man-update +[…]$ ykpersonalize -2 -o append-cr -a 123456deadcafebeef65432112345678 -o -man-update This writes a static key to the YubiKey based on the 32-byte AES key specified with the -a option. The -2 option sets the second slot as target. The other two options are a matter of personal taste. The append-cr option sends a carriage return as the last character of the key. That way I do not have to press myself. The -man-update option disables easy updating of the static key in the YubiKey. Enabling this will allow for altering the static password without the use of ykpersonalize. @@ -192,7 +192,7 @@ This writes a static key to the YubiKey based on the 32-byte AES key specified w If we want to write a new configuration to the first slot of the key, we need to specify some more options. If you want to be able to upload you key to Yubico, in order to authenticate against their servers, remember what the values are that you use below. You will need them later on. [source, bash] -[…]$ ykpersonalize -1 -ofixed=vvhhhrhkhgidic -ouid=deadbeefcafe -a123456deadcfaebeef65432112345678 -oappend-cr +[…]$ ykpersonalize -1 -o fixed=vvhhhrhkhgidic -o uid=deadbeefcafe -a 123456deadcfaebeef65432112345678 -o append-cr The -1 option tells ykpersonalize to use the first configuration. The fixed option specifies the public ID of the YubiKey. This is referred to as the 'prefix' later on, when we go uploading it. The value you use here has to start with 'ff' in hex or 'vv' in modhex (xref:#_what_is_modhex[see below]). Yubico enforces this when you try to upload your key to their servers. The value for the fixed option can be up to 16 characters in length. From 90432a73763f2bcd1fcf5523b20acd3a23d82da3 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sat, 18 Feb 2023 11:00:39 +0100 Subject: [PATCH 11/17] pages/yubikey: fix several grammar issues --- modules/ROOT/pages/using-yubikeys.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 2f97fd0..b13475f 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -200,7 +200,7 @@ As part of the OTP, you can specify an internal identifier for your key. This is The -a option, again, is the 32-byte AES key and append-cr appends a carriage return to my key as the last character. -When I hit the key, the ykpersonalize program will present me with my options and ask for +When you hit the key, the ykpersonalize program will present you with my options and ask for confirmation before continuing: ==== @@ -264,7 +264,7 @@ https://www.yubico.com/authentication-standards/fido2/[FIDO2] is an open authent One interesting use case of the FIDO module to note is storing OpenSSH public-key identities, which modern OpenSSH agents can pick up right away and use. This makes ssh keys quite portable. -If your key supports FIDO change it's pin with ykman fido access like this: +If your key supports FIDO change its pin with ykman fido access like this: [source, bash] […]$ ykman piv access change-pin @@ -313,7 +313,7 @@ Generate a public key on every host you intend to use the private key, so an Ope [source, bash] […]$ ssh-keygen -t ed25519-sk -Generate the public key and store it's identity in the FIDO2 module to make the private-public key-pair portable: +Generate the public key and store its identity in the FIDO2 module to make the private-public key-pair portable: [source, bash] […]$ ssh-keygen -t ed25519-sk -O resident -O application=ssh:fedora -O verify-required @@ -325,7 +325,7 @@ So called resident keys require that the private key is protected by a PIN. As of 2019, there is work in place to attempt to standardize using a YubiKey on the web. The new standard is called WebAuthn, and you can learn more about it here: https://www.yubico.com/solutions/webauthn/. For now, the easiest way to see which platforms support the YubiKey is by browsing https://www.yubico.com/works-with-yubikey/catalog/[yubico's catalog]. -As an alternative to Yubico OTP or WebAuthn, which both don't require storage of credentials on the YubiKey by default, you may also use plain old TOTP like employed in most websites today. There are desktop and at least android apps to work with this conveniently. You may store up to 32 TOTP credentials on a YubiKey 5. +As an alternative to Yubico OTP or WebAuthn, neither of which require storage of credentials on the YubiKey by default, you may also use plain old TOTP like employed in most websites today. There are desktop and at least android apps to work with this conveniently. You may store up to 32 TOTP credentials on a YubiKey 5. Install the desktop application from the official repositories: From eae11f04885b29c237a42e4f9a9ec03e2aa69488 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 19 Feb 2023 12:01:00 +0100 Subject: [PATCH 12/17] pages/yubikey: add missing line in example --- modules/ROOT/pages/using-yubikeys.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index b13475f..15ecc23 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -122,6 +122,7 @@ The result looks similar to this: [source] #%PAM-1.0 +auth include yubikey-sufficient auth substack system-auth auth include postlogin account required pam_nologin.so From 6619d128b8197314fdface438cb449913789f7a8 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Mon, 20 Feb 2023 20:31:33 +0100 Subject: [PATCH 13/17] pages/yubikey: fix key registration instructions The instructions to register a key with the local account were implicitly requiring challenge-response. Add the YubiCloud method based instructions and also add an explicit command to configure challenge-response in slot 2 of a key. --- modules/ROOT/pages/using-yubikeys.adoc | 35 +++++++++++++++++++------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 15ecc23..c4298da 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -49,15 +49,7 @@ Install the PAM yubico module from the official repositories: [source, bash] […]$ sudo dnf install pam_yubico -Register a currently connected YubiKey with your user account with - -[source, bash] -[…]$ ykpamcfg -2 -v - -Or for any other system user using sudo with - -[source, bash] -[…]$ sudo -u someuser ykpamcfg -2 -v +=== Base configuration files Create two base configuration files in /etc/pam.d. yubikey-required and yubikey-sufficient. @@ -99,6 +91,31 @@ auth sufficient pam_yubico.so mode=challenge-response You may add the debug option at the end of these lines right after the mode option to get troubleshooting information in journald. ==== +=== Register YubiKey(s) with your local account(s) + +If you use the online YubiCloud method you need the ID of your YubiKey. For this just enter the key and retrieve an OTP code with a short press on the button and extract the first 12 characters - this is your key ID. + +[source] +cccccbcgebif | bclbtjihhbfbduejkuhgvhkehnicrfdj + +Create a configuration file ~/.yubico/authorized_keys with your user account followed by key IDs separated by semicolons. + +[source] +fedora-user:cccccbcgebif[:] + +Alternatively, activate challenge-response in slot 2 and register with your user account. + +[source, bash] +[…]$ ykman otp chalresp --generate --touch 2 +[…]$ ykpamcfg -2 + +Or for any other system user using sudo. + +[source, bash] +[…]$ sudo -u someuser ykpamcfg -2 + +=== Configure desired PAM modules + Next configure PAM to accept a YubiKey as a means of authentication. There are many options in /etc/pam.d to modify and add a YubiKey, but the most common use-cases are: - /etc/pam.d/login From dafcba998855880ab57926591f7fea755ef52008 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 26 Feb 2023 11:50:50 +0100 Subject: [PATCH 14/17] pages/yubikey: add note about using both auth methods --- modules/ROOT/pages/using-yubikeys.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index c4298da..7939402 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -91,6 +91,8 @@ auth sufficient pam_yubico.so mode=challenge-response You may add the debug option at the end of these lines right after the mode option to get troubleshooting information in journald. ==== +If you want to use both methods for different use-cases just create the respective configuration files and use them as includes as described in the next section accordingly. + === Register YubiKey(s) with your local account(s) If you use the online YubiCloud method you need the ID of your YubiKey. For this just enter the key and retrieve an OTP code with a short press on the button and extract the first 12 characters - this is your key ID. From b015b9954cd710d1bc9fffb04a758c1fd579cc5c Mon Sep 17 00:00:00 2001 From: w4tsn Date: Sun, 26 Feb 2023 11:52:18 +0100 Subject: [PATCH 15/17] pages/yubikey: add warning about online auth method --- modules/ROOT/pages/using-yubikeys.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index 7939402..be0b847 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -1,7 +1,7 @@ = Using YubiKeys with Fedora The Fedora docs team :revnumber: unknown -:revdate: 2023-02-12 +:revdate: 2023-02-26 :category: Using // :tags: From Source @@ -68,6 +68,11 @@ auth sufficient pam_yubico.so id=[Your API Client ID] key=[Your API Cl Note that the key is optional but without it there is no TLS verification which makes this susceptible to MitM attacks by default. Obtain a key at https://upgrade.yubico.com/getapikey[Yubico]. ==== +[CAUTION] +==== +Note that the online auth method won't work if the device is offline and can't reach the YubiCloud. +==== + [NOTE] ==== If you have SELinux on the enforcing mode (the default mode), you should flip on the allow_ypbind boolean first, because pam_yubico needs to be able to connect to Yubico's online authentication. servers. From 099c592e5b39d070d139d5e3f04dc9a38a076ff0 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Mon, 27 Feb 2023 09:46:23 +0100 Subject: [PATCH 16/17] pages/yubikey: fix typo --- modules/ROOT/pages/using-yubikeys.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index be0b847..e153de4 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -105,7 +105,7 @@ If you use the online YubiCloud method you need the ID of your YubiKey. For this [source] cccccbcgebif | bclbtjihhbfbduejkuhgvhkehnicrfdj -Create a configuration file ~/.yubico/authorized_keys with your user account followed by key IDs separated by semicolons. +Create a configuration file ~/.yubico/authorized_keys with your user account followed by key IDs separated by colons. [source] fedora-user:cccccbcgebif[:] From 970eb0ebb14d148cae0602f524afbeceed97e861 Mon Sep 17 00:00:00 2001 From: w4tsn Date: Tue, 28 Feb 2023 21:16:41 +0100 Subject: [PATCH 17/17] pages/yubikey: fix yubikey-manager gui package --- modules/ROOT/pages/using-yubikeys.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/using-yubikeys.adoc b/modules/ROOT/pages/using-yubikeys.adoc index e153de4..066c339 100644 --- a/modules/ROOT/pages/using-yubikeys.adoc +++ b/modules/ROOT/pages/using-yubikeys.adoc @@ -194,7 +194,7 @@ There is a more recent, simpler tool, ykman: YubiKey manager also has a gui: [source, bash] -[…]$ sudo dnf install yubikey-manager-gui +[…]$ sudo dnf install yubikey-manager-qt === Writing a new static password to the second slot of the key