Menggunakan YubiKey dengan Fedora

The Fedora Documentation Team, Alexander Wellbrock, chris-r Versi F43 Last review: 2026-02-28

Apa itu YubiKey?

YubiKey adalah perangkat kecil berbasis USB dan NFC, disebut juga token keamanan perangkat keras, dengan modul untuk berbagai penggunaan yang berkaitan dengan keamanan. Alat ini menghasilkan kata sandi sekali pakai (OTP), menyimpan kunci privat, dan secara umum menerapkan berbagai protokol autentikasi. Perangkat ini dibuat dan dijual oleh perusahaan bernama Yubico.

Untuk informasi lebih lanjut tentang fitur YubiKey, lihat halaman produk mereka.

Bagaimana cara mendapatkan YubiKey?

Anda dapat membeli YubiKey dari situs web Yubico.

Pertimbangkan YubiKey cadangan

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 them 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.

In practice this means registering both hardware tokens with your Linux and web accounts, generating private keys twice, and configuring both public keys at e.g. github.

Keterbatasan penyimpanan

For some features, private keys and other secrets are stored on the YubiKey. Each feature has its own storage space, and hence maximum number of credential slots:

  • OTP - Tidak terbatas, karena hanya memerlukan satu rahasia per kunci

  • FIDO U2F - Tidak terbatas, karena hanya memerlukan satu rahasia per kunci

  • FIDO2 - 25 kredensial

  • OATH - 32 kredensial

  • PIV - 24 sertifikat x509 beserta kunci privatnya masing-masing

  • OpenPGP - 3 kunci; masing-masing untuk enkripsi, tanda tangan, dan autentikasi

Menggunakan YubiKey untuk mengautentikasi ke mesin dengan Fedora

Local system authentication uses Pluggable Authentication Modules (PAM). You have two options here: pam_yubico and pam_u2f. The former is required for YubiKeys without FIDO2/U2F. Whether your key supports the FIDO2 standard depends on the firmware and hardware model.

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 with.

Dependensi

Paket yang diperlukan untuk kedua modul PAM tersedia di repositori resmi.

=== Note that one difference between both PAM modules is that with pam_yubico you don’t need to touch your YubiKey. It’s enough if the key is inserted in your device. With pam_u2f, you have to touch your key every time authentication is required. ===

Untuk pam_yubico

Instal modul PAM yubico dari repositori resmi:

[…]$ sudo dnf install pam_yubico

Untuk pam_u2f

Instal modul PAM u2f dan alat CLI dari repositori resmi:

[…]$ sudo dnf install pam-u2f pamu2fcfg

Berkas konfigurasi dasar

Untuk pam_yubico

Ada dua cara untuk mengonfigurasi modul PAM YubiKey agar dapat mengautentikasi pengguna, yaitu melalui YubiCloud atau menggunakan challenge-response. YubiCloud adalah metode standar tetapi bergantung pada layanan cloud Yubico untuk memverifikasi OTP Anda dan karenanya memerlukan koneksi internet yang terus aktif.

Buat dua berkas konfigurasi dasar di /etc/pam.d/yubikey-required dan yubikey-sufficient.

For YubiCloud, use the following:

#%PAM-1.0
auth       required     pam_yubico.so id=[Your API Client ID] key=[Your API Client Key]
#%PAM-1.0
auth       sufficient     pam_yubico.so id=[Your API Client ID] key=[Your API Client Key]

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 Yubico.

Perhatikan bahwa metode autentikasi daring tidak akan berfungsi jika perangkat dalam keadaan offline dan tidak dapat menjangkau YubiCloud.

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.

[…]$ sudo setsebool -P allow_ypbind=1

For challenge-response, use the following:

#%PAM-1.0
auth       required     pam_yubico.so mode=challenge-response
#%PAM-1.0
auth       sufficient     pam_yubico.so mode=challenge-response

Anda dapat menambahkan opsi debug di akhir baris ini tepat setelah opsi mode untuk mendapatkan informasi pemecahan masalah di 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.

Untuk pam_u2f

Buat dua berkas konfigurasi dasar di /etc/pam.d/u2f-required dan u2f-sufficient.

#%PAM-1.0
auth       required     pam_u2f.so
#%PAM-1.0
auth       sufficient     pam_u2f.so

Anda dapat menambahkan opsi debug di akhir baris ini tepat setelah opsi mode untuk mendapatkan informasi pemecahan masalah di journald.

Daftarkan YubiKey dengan akun lokal Anda

Untuk pam_yubico

If you are using 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.

cccccbcgebif | bclbtjihhbfbduejkuhgvhkehnicrfdj

Create a configuration file ~/.yubico/authorized_yubikeys with your user account, followed by key IDs separated by colons.

fedora-user:cccccbcgebif[:<another-key-id>]

Sebagai alternatif, aktifkan challenge-response di slot 2 dan daftarkan dengan akun pengguna Anda. Perintah pertama (ykman) dapat dilewati jika Anda sudah memiliki kredensial challenge-response yang tersimpan di slot 2 pada YubiKey. (Verifikasi dengan 'ykman otp info') Ulangi kedua langkah atau hanya langkah terakhir jika Anda memiliki kunci cadangan (sangat disarankan).

[…]$ ykman otp chalresp --generate --touch 2 […]$ ykpamcfg -2
Tantangan awal dan respons yang diharapkan disimpan di '/home/<username>/.yubico/challenge-1...5'.

Atau untuk pengguna sistem lainnya dengan menggunakan sudo.

[…]$ sudo -u someuser ykpamcfg -2

Untuk pam_u2f

Use the tool pamu2fcfg to retrieve a configuration line that goes into ~/.config/Yubico/u2f_keys. This configuration line consists of a username and a part tied to a key separated by a colon.

fedora-user:owBYtPIH2yzjlSQaRrVcxB...Pg==,es256,+presence

If the key is PIN protected, you’ll be asked to enter the PIN for this operation.

[…]$ mkdir -p ~/.config/Yubico […]$ pamu2fcfg > ~/.config/Yubico/u2f_keys

If you have a backup key, add it with the --nouser option and append it to the existing key (line). (All output should end up in the same line.)

[…]$ pamu2fcfg -n >> ~/.config/Yubico/u2f_keys

Konfigurasikan modul PAM yang diinginkan

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

  • /etc/pam.d/gdm

  • /etc/pam.d/sudo

  • /etc/pam.d/sshd

In a PAM configuration file, if using {yubikey,u2f}-sufficient, add an include line before, or if using {yubikey,u2f}-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:

auth include yubikey-sufficient

The following example sets a YubiKey OTP as a 'sufficient' factor for terminal login. This means that a YubiKey alone is enough to authenticate a user when logging in on a terminal.

Buka /etc/pam.d/login dengan editor teks pilihan Anda. Temukan baris yang berisi "auth substack system-auth". Di atasnya, sisipkan baris berikut:

auth include yubikey-sufficient

Hasilnya akan terlihat seperti ini:

#%PAM-1.0
auth       include      yubikey-sufficient
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

Next time you open a console (local, not an SSH session) and attempt to log in, you should be prompted YubiKey for '<user>':. Tap your YubiKey to input an OTP, and you will be logged in without entering a password.

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 just the 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.

Menyesuaikan YubiKey dengan Fedora

YubiKey hadir dengan konfigurasi awal untuk Yubico OTP, tetapi selain itu menggunakan PIN default untuk setiap fitur lainnya yang kemungkinan besar ingin Anda ubah sebelum digunakan. Tersedia perangkat lunak untuk menyesuaikan YubiKey di repositori resmi.

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.

[…]$ sudo dnf install ykpers

Tersedia GUI untuk perintah ini:

[…]$ sudo dnf install yubikey-personalization-gui

Ada alat yang lebih baru dan lebih sederhana bernama ykman:

[…]$ sudo dnf install yubikey-manager

YubiKey Manager juga memiliki GUI:

[…]$ sudo dnf install yubikey-manager-qt

Menulis kata sandi statis baru ke slot kedua pada kunci

YubiKey generasi baru (YubiKey 2+) memiliki kemampuan untuk menyimpan dua konfigurasi terpisah. Konfigurasi pertama umumnya digunakan untuk OTP, sedangkan konfigurasi kedua untuk kata sandi statis yang kuat. Jika tombol ditekan sebentar, kurang dari 1,5 detik, konfigurasi pertama akan aktif. Jika tombol ditekan lebih lama, antara 2,5 hingga 5 detik, maka konfigurasi kedua yang akan aktif.

Tulis kunci statis menggunakan ykman otp static.

[…]$ ykman otp static 2 cbdefghijklnrtuv

Contoh yang lebih lengkap: menulis kunci statis baru ke slot konfigurasi kedua dengan menggunakan kunci AES tertentu.

[…]$ 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 the 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 you do not have to press <ENTER> yourself. 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.

Menulis kunci AES baru ke slot pertama pada kunci

Slot 1 is special as it contains a factory credential already uploaded to YubiCloud. Deleting and recreating a Yubico OTP secret and uploading it to YubiCloud yourself will put a special mark on it, which has consequences: service providers might not trust such a key, and Yubico might delete those secrets at any time for practically any reason.

Untuk menulis konfigurasi baru ke slot pertama pada kunci, Anda perlu menentukan beberapa opsi tambahan. Jika ingin dapat mengunggah kunci ke Yubico agar bisa melakukan autentikasi ke server mereka, ingatlah nilai yang Anda gunakan pada bagian ini. Anda akan membutuhkannya nanti.

[…]$ 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 are uploading it. The value you use here has to start with 'ff' in hex or 'vv' in 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.

Sebagai bagian dari OTP, Anda dapat menentukan pengenal internal untuk kunci Anda. Inilah yang dilakukan oleh opsi uid. Nilainya berupa hex biasa, bukan modhex, dan ''harus'' terdiri dari 12 karakter.

Opsi -a, sekali lagi, adalah kunci AES 32-byte dan append-cr akan menambahkan karakter carriage return sebagai karakter terakhir pada kunci.

Ketika Anda menekan tombol <ENTER>, program ykpersonalize akan menampilkan opsi yang Anda pilih dan meminta konfirmasi sebelum melanjutkan:

Firmware version 2.1.1 Touch level 1795 Program sequence 3 Configuration data to be written to key configuration 1:

fixed: m:vvhhhrhkhgidic uid: h:deadbeefcafe key: h:123456deadcfaebeef65432112345678 acc_code: h:000000000000 ticket_flags: APPEND_CR config_flags:

Commit? (y/n) [n]:

After pressing 'y', you are able to generate OTPs with your new key!

Apa itu modhex?

Ketika terhubung, sistem operasi memperlakukan YubiKey sebagai keyboard USB. Keyboard USB mengirim scancode ke sistem operasi, yang kemudian diinterpretasi sebagai penekanan tombol. YubiKey harus memastikan agar tidak terjadi ambiguitas: ada banyak tata letak keyboard yang berbeda, dan scancode tersebut harus diinterpretasi sebagai karakter yang sama di semua jenis tata letak keyboard. Untuk mengatasi hal ini, tim Yubico menciptakan 'modhex', yaitu representasi khusus dari karakter heksadesimal yang hanya menggunakan karakter 'aman'. Karakter 'aman' adalah karakter yang memiliki scancode sama pada semua tata letak keyboard.

Mengunggah kunci AES yang dihasilkan ke Yubico

Jika Anda ingin menyesuaikan kunci AES YubiKey Anda namun tetap ingin menggunakannya untuk autentikasi melalui server Yubico, Anda dapat mengunggah kunci tersebut melalui https://upgrade.yubico.com/getapikey/. Anda akan diminta untuk memasukkan alamat email dan OTP dari YubiKey Anda.

Perbarui PIN pada modul PIV

The Personal Identity 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.

Atur PIN.

[…]$ ykman piv access change-pin Enter the current PIN: 123456 Enter the new PIN: ******** Repeat for confirmation: ******** New PIN set.

Atur PUK.

[…]$ ykman piv access change-puk Enter the current PUK: 12345678 Enter the new PUK: ******** Repeat for confirmation: ******** New PUK set.

Perbarui Management Key.

[…]$ ykman piv access change-management-key --generate --protect Enter the current management key [blank to use default key]: Enter PIN: ********

Sekarang Anda dapat menggunakan modul PIV dengan aman untuk membuat kunci privat dan menyimpan sertifikat.

Ubah PIN pada modul FIDO2

FIDO2 adalah standar autentikasi terbuka yang mencakup sub-standar dan protokol untuk menyediakan metode autentikasi dua faktor atau bahkan tanpa kata sandi (passwordless).

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 its PIN with ykman fido access like this:

[…]$ ykman piv access change-pin Enter the current PIN: 123456 Enter the new PIN: ******** Repeat for confirmation: ******** New PIN set.

Konfigurasikan kata sandi untuk OATH

Fitur OATH menyediakan protokol autentikasi TOTP dan HOTP. Fitur ini dapat dilindungi dengan frasa sandi untuk mengakses dan menghasilkan kode OTP. Hal ini berbeda dengan fitur Yubico OTP, yang menggunakan satu rahasia tersimpan di YubiKey untuk challenge-response.

Ubah kata sandi OATH dengan perintah berikut:

[…]$ ykman oath access change Enter the new password: Repeat for confirmation:

Konfigurasikan perangkat Anda agar mengingat kata sandi ini sehingga Anda tidak perlu memasukkannya kembali.

[…]$ ykman oath access remember

Menggunakan YubiKey untuk autentikasi ke server OpenSSH

Using FIDO2 and OpenSSH 8.2+, you can generate OpenSSH keys that are only usable if the YubiKey is connected. It’s possible to protect the key usage by either presence or presence + PIN-entry.

Hasilkan kunci publik di setiap host yang ingin Anda gunakan bersama kunci privat, sehingga agen OpenSSH dapat menemukannya:

[…]$ ssh-keygen -t ed25519-sk

Hasilkan kunci publik dan simpan identitasnya di dalam modul FIDO2 agar pasangan kunci publik-privat menjadi portabel:

[…]$ ssh-keygen -t ed25519-sk -O resident -O application=ssh:fedora -O verify-required
So-called resident keys require that the private key be protected by a PIN.

Alternatif untuk kunci tanpa dukungan FIDO2

If the key does not support FIDO2, you have to use an alternative method via the PIV module and PKCS#11.

Buat kunci privat ED25519 di dalam modul PIV yang memerlukan masukan PIN setiap kali digunakan dan harus selalu menyentuh tombol YubiKey:

[…]$ ykman piv keys generate --algorithm ED25519 --pin-policy ONCE --touch-policy ALWAYS 9a public.pem Enter PIN: ********

Slot 9a pada kunci dikhususkan untuk autentikasi. Tersedia slot lainnya untuk fitur seperti enkripsi atau tanda tangan.

Buat sertifikat pada slot yang sama untuk pustaka PIV/PKCS#11:

[…]$ ykman piv certificates generate --subject "CN=OpenSSH" --hash-algorithm SHA384 9a pubkey.pem Enter PIN: ******** Touch your YubiKey…

Sekarang hasilkan kunci publik dari sertifikat X.509 yang disimpan di YubiKey. Fitur lain seperti resident key berfungsi sama seperti pendekatan FIDO2, tetapi Anda harus menambahkan opsi tambahan seperti contoh di bawah ini.

[…]$ ssh-keygen -D /usr/lib/libykcs11.so -e

Log in to systems using this public key:

[…]$ ssh -I /usr/lib/libykcs11.so user@remote.example.org

ssh-agent juga dapat memuat kunci dari YubiKey dengan perintah berikut:

[…]$ ssh -s /usr/lib/libykcs11.so

Menggunakan YubiKey untuk autentikasi ke situs web

Sejak tahun 2019, sedang dilakukan upaya untuk menstandarkan penggunaan YubiKey di web. Standar baru ini disebut WebAuthn, dan Anda dapat mempelajarinya lebih lanjut di https://www.yubico.com/solutions/webauthn/. Untuk saat ini, cara termudah untuk melihat platform mana saja yang mendukung YubiKey adalah dengan menelusuri katalog Yubico.

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.

Instal aplikasi desktop dari repositori resmi:

[…]$ sudo dnf install -y yubioath-desktop

Tambahkan akun TOTP dengan ykman seperti berikut:

[…]$ ykman oath accounts add google <TOTP secret>

Ambil kode TOTP dengan cara berikut:

[…]$ ykman oath accounts code google

Want to help? Learn how to contribute to Fedora Docs ›