Utilizar YubiKeys con Fedora

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

¿Qué es un YubKey?

Un YubiKey es un dispositivo pequeño basado en USB y NFC, un llamado como vale de seguridad hardware, con módulos para muchos casos de uso relacionados con la seguridad. Genera una vez las contraseñas (OTP), almacena llaves privadas e implementa protocolo de autenticación diferente. Son creados y vendidos por medio de una empresa llamada Yubico.

Para más información sobre características YubiKey, consulte su página del producto.

¿Como obtengo un YubiKey?

Puede adquirir una YubiKey desde el sitio web de Yubico.

Considere un respaldo de YubiKey

Al empezar a trabajar con vales de seguridad, debe tener en cuenta la posibilidad de bloquear las cuentas vinculadas a ellos. Dado que los vales de seguridad de hardware son únicos y están diseñados para ser extremadamente difíciles de copiar, no se puede simplemente hacer una copia de seguridad como con bóvedas de software como Keepass o AndOTP. Por ello, todos los registros que realice con su clave principal deben hacerse inmediatamente con una segunda clave de respaldo que guarde en un lugar seguro, como una caja fuerte, o al menos, que siempre tenga en casa.

En la práctica esto significa registrar ambos vales de hardware con sus cuentas de Linux y web, genera una pareja de claves privadas, y configurar ambas claves públicas p.ej. en github.

Limitaciones de almacén

Para algunas características, las claves privadas y otros secretos son almacenados en el YubiKey. Cada capacidad tiene sus propios espacios de almacén y, por tanto en el número máximo de ranuras de credencial:

  • OTP: Ilimitado, ya que solo se requiere un secreto por clave

  • FIDO U2F - Ilimitado, como solo un secreto por clave es requerido

  • FIDO2 - 25 credenciales

  • OATH - 32 credenciales

  • PIV: 24 certificados x509 y sus claves privadas respectivas

  • Las claves OpenPGP - 3 claves; cada una para cifrado, firma y autenticación

Utilizando Yubikey para autenticar a una máquina ejecutando Fedora

La autenticación del sistema local utiliza Módulos de Autenticación Enchufables (PAM). Tiene dos opciones: pam_yubico y pam_u2f. La primera es necesaria para las YubiKeys sin FIDO2/U2F. Si su clave es compatible con el FIDO2 estándar, depende del firmware y el modelo de hardware.

La configuración es la siguiente: instale el módulo PAM, registra una YubiKey con tu cuenta de usuario, crea una configuración base para cualquiera de las dos opciones de autenticación, y luego elije la configuración PAM con la que deseas utilizar la YubiKey.

Dependencias

El paquete requerido para ambos módulos PAM están disponibles en los repositorios oficiales.

=== Tenga en cuenta que una diferencia entre ambos módulos PAM es que con pam_yubico no es necesario tocar tu llave YubiKey. Basta si la llave está insertada dentro de su dispositivo. Con pam_u2f, tienes que tocar tu llave cada vez que es requerida la autenticación. ===

Para pam_yubico

Instale el módulo PAM yubico desde los repositorios oficiales:

$ sudo dnf install pam_yubico

Para pam_u2f

Instala el módulo u2f de PAM y la herramienta CLI desde los repositorios oficiales:

$ sudo dnf install pam-u2f pamu2fcfg

Archivos de configuración base

Para pam_yubico

Hay dos maneras de configurar el módulo PAM de YubiKey para autenticar usuarios: a través de YubiCloud o mediante desafío-respuesta. YubiCloud es el método estándar, pero depende de la nube de YubiCo para validar sus OTP y, por lo tanto, requiere acceso constante a internet.

Cree dos archivos de configuración base en /etc/pam.d/yubikey-required y yubikey-sufficient.

Para YubiCloud, utiliza lo siguiente:

#%PAM-1.0
auth       required     pam_yubico.so id=[Tu ID de cliente API] key=[Tu llave de Cliente API]
#%PAM-1.0
auth       sufficient     pam_yubico.so id=[Tu ID Cliente de API] key=[Tu Llave de Cliente API]

Tenga en cuenta que la clave es opcional, pero sin ella no hay verificación TLS, lo que la hace susceptible a ataques MitM de forma predeterminada. Obtenga una clave en Yubico.

Tenga en cuenta que el método de autenticación en línea no funcionará si el dispositivo está fuera de línea y no puede acceder a YubiCloud.

Si tiene SELinux en el modo reforzado (el modo predeterminado), primero deberías activar el booleano allow_ypbind, porque pam_yubico necesita ser capaz de conectar a los servidores de autenticación en línea de Yubico.

$ sudo setsebool -P allow_ypbind=1

Para el desafío-respuesta, utilice lo siguiente:

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

Puede agregar la opción de depuración al final de estas líneas justo después de la opción de modo para obtener información de solución de problemas en journald.

Si desea utilizar ambos métodos para diferentes casos de uso, simplemente cree los archivos de configuración respectivos y utilícelos como inclusiones tal como se describe en la siguiente sección.

Para pam_u2f

Habilita pam_u2f utilizando authselect (recomendado)

Authselect es la manera recomendada de integrar pam_u2f dentro de la configuración de PAM en Fedora. Esto habilita autenticación U2F dentro de la pila PAM de una manera que es consistente a través de servicios y actualizaciones del sistema.

Antes de habilitar la característica, asegúrese que tenga registrado su clave de seguridad (consulte la sección Register YubiKey(s) with your local account(s)) de modo que pam_u2f pueda encontrar su archivo u2f_keys.

Mantener una raíz de shell o una sesión de acceso adicional abierta mientras cambie los ajustes de autenticación y cambiar las pruebas antes de salir. La configuración incorrecta puede bloquearle fuera del sistema.

Marque el perfil actual authselect:

$ sudo authselect current

Habilita mantenimiento U2F en el perfil actual para añadir la característica with-pam-u2f. Utilice el mismo Profile ID que es asomado por authselect current. Por ejemplo:

$ sudo authselect select sssd with-pam-u2f

o:

$ sudo authselect select local with-pam-u2f

Aplica los cambios (si necesario):

$ sudo authselect apply-changes

Autentificación de prueba en una sesión terminal nueva (p.ej., con sudo) antes de cerrar sesión:

$ sudo -k
$ sudo true
Avanzado: Manual de configuración de PAM para pam_u2f (no recomendado)

Las modificaciones manuales de los archivos de configuración de PAM pueden provocar inconsistencias o incluso impedir el acceso de los usuarios al sistema. Authselect gestiona estas configuraciones mediante perfiles predefinidos y ayuda a mantener la compatibilidad tras las actualizaciones del sistema.

Cree dos archivos de configuración base en /etc/pam.d/u2f-required y u2f-sufficient.

Los archivos /etc/pam.d/u2f-required y /etc/pam.d/u2f-sufficient son archivos incluidos en PAM. Al crearlos no habilita autenticación U2F por sí mismo.

Para utilizarlos, debe incluir uno de estos archivos en la configuración PAM del servicio deseado (por ejemplo, login, sudo, sshd, gdm/sddm), como se describe en la siguiente sección.

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

Puede agregar la opción de depuración al final de estas líneas justo después de la opción de modo para obtener información de solución de problemas en journald.

Registra tu(s) YubiKey(s) con tu(s) cuenta(s) local(es)

Para pam_yubico

Si utilizas el método en conexión de YubiCloud, necesitas el ID de tu YubiKey. Para ello, introduce la clave y recibe un código OTP pulsando brevemente el botón. Extrae los primeros 12 caracteres: este es el ID de tu clave.

cccccbcgebif | bclbtjihhbfbduejkuhgvhkehnicrfdj

Crea un archivo de configuración ~/.yubico/authorized_yubikeys con tu cuenta de usuario, seguido de los ID de las claves separados por dos puntos.

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

Como alternativa, active la autenticación de desafío-respuesta en la ranura 2 y regístrese con su cuenta de usuario. Puede omitir el primer comando (ykman) si ya tiene una credencial de desafío-respuesta almacenada en la ranura 2 de su YubiKey. (Verifíquelo con 'ykman otp info'). Repita ambos pasos o solo el último si tiene una clave de respaldo (muy recomendable).

$ ykman otp chalresp --generate --touch 2
$ ykpamcfg -2
El desafío inicial y la respuesta esperada se almacenaron en '/home/<nombre‐usuario>/.yubico/challenge-1...5'.

O para cualquier otro usuario del sistema que utilice sudo.

$ sudo -u someuser ykpamcfg -2

Para pam_u2f

Utilice la herramienta pamu2fcfg para obtener una línea de configuración que se guarda en ~/.config/Yubico/u2f_keys. Esta línea de configuración consta de un nombre de usuario y una parte vinculada a una clave, separados por dos puntos.

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

Si la llave está protegida con un PIN, se le pedirá que introduzca el PIN para realizar esta operación.

Insert your key and run:

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

Si dispone de una clave de respaldo, agréguela con la opción --nouser y añádala a la clave existente (línea). (Toda la salida debe aparecer en la misma línea).

Insert your backup key and run:

$ pamu2fcfg -n >> ~/.config/Yubico/u2f_keys

Configurar los módulos PAM deseados

A continuación, configure PAM para que acepte una YubiKey como método de autenticación. Existen muchas opciones en /etc/pam.d para modificar y agregar una YubiKey, pero los casos de uso más comunes son:

  • /etc/pam.d/login

  • /etc/pam.d/gdm

  • /etc/pam.d/sudo

  • /etc/pam.d/sshd

Configurar los módulos PAM deseados

A continuación, configure PAM para que acepte una YubiKey como método de autenticación. Existen muchas opciones en /etc/pam.d para modificar y agregar una YubiKey, pero los casos de uso más comunes son:

  • /etc/pam.d/login

  • /etc/pam.d/gdm

  • /etc/pam.d/sudo

  • /etc/pam.d/sshd

In a PAM configuration file, add the include line either before or after the existing system-auth line, depending on whether you use a -sufficient or -required include file:

  • If using a -sufficient include, add it *before auth substack system-auth (or auth include system-auth).

  • If using a -required include, add it *after that line.

The include file name depends on which PAM module you configured earlier:

  • For pam_yubico, use yubikey-sufficient or yubikey-required

  • For pam_u2f (manual PAM configuration), use u2f-sufficient or u2f-required

If you enabled pam_u2f via authselect (recommended), you usually do not need to edit individual /etc/pam.d/* files manually.

Examples:

auth include yubikey-sufficient
auth include u2f-sufficient

The following example sets a YubiKey OTP (pam_yubico) 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.

Open /etc/pam.d/login with your editor of choice. Find the line that reads "auth substack system-auth". Above that, insert:

auth include yubikey-sufficient

El resultado parece similar a esto:

#%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

La próxima vez que abras una consola (local, no una sesión SSH) e intentes iniciar sesión, se te pediría que introduzcas tu YubiKey para '<usuario>':. Pulsa tu YubiKey para introducir un código OTP, y accederás sin necesidad de una contraseña.

Al usar la opción yubikey‐required, asegúrese de probarla exhaustivamente en otra sesión sin cerrar la actual para evitar quedarse fuera del sistema.

Para agregar una YubiKey a algo más que el inicio de sesión en la terminal, como servidores sshd locales, sudo o inicio de sesión GDM, agregue la inclusión de autenticación correspondiente a uno de los otros archivos de configuración en /etc/pam.d.

Personalización de una YubiKey con Fedora

Una YubiKey viene pre‐configurada para Yubico OTP, pero para el resto de funciones utiliza PIN predeterminado que probablemente querrás cambiar antes de usarla. Existe software para personalizar la YubiKey en los repositorios oficiales.

Básicamente, existen dos herramientas que se pueden usar junto con sus respectivas interfaces gráficas de usuario (IGU): 'yubikey-manager' y 'ykpersonalize'. La primera es más reciente, pero ofrece menos opciones que la segunda. Para acceder a todas las opciones disponibles, instale ambas.

$ sudo dnf install ykpers

Existe una interfaz gráfica de usuario para este comando:

$ sudo dnf install yubikey-personalization-gui

Existe una herramienta más reciente y sencilla, ykman:

$ sudo dnf install yubikey-manager

El gestor de YubiKey también tiene una interfaz gráfica de usuario:

$ sudo dnf install yubikey-manager-qt

Escribir una contraseña estática nueva en la segunda ranura de la clave

Las YubiKeys nuevas (YubiKey 2+) tienen la capacidad de almacenar dos configuraciones separadas. La primera se usa generalmente para códigos OTP, y la segunda para una contraseña segura y estática. Si se pulsa el botón brevemente, hasta 1'5 segundos, se activa la primera configuración. Si se pulsa durante más tiempo, entre 2'5 y 5 segundos, se activa la segunda.

Escribe una clave estática usando ykman otp static.

$ ykman otp static 2 cbdefghijklnrtuv

Un ejemplo más elaborado: escribir una nueva clave estática en la segunda ranura de configuración utilizando una clave AES específica.

$ ykpersonalize -2 -o append-cr -a 123456deadcafebeef65432112345678 -o -man-update

Esto escribe una clave estática en la YubiKey basada en la clave AES de 32‐byte especificada con la opción -a. La opción -2 establece la segunda ranura como destino. Las otras dos opciones son cuestión de preferencia personal. La opción append-cr envía un retorno de carro como último carácter de la clave. De esta forma, no es necesario pulsar <ENTRAR> manualmente. La opción -man-update inhabilita la actualización sencilla de la clave estática en la YubiKey. Habilitarla permitirá modificar la contraseña estática sin usar ykpersonalize.

Escribir una clave AES nueva en la primera ranura de la clave

La ranura 1 es especial, ya que contiene una credencial de fábrica que ya se ha subido a YubiCloud. Si eliminas y vuelves a crear una clave secreta OTP de Yubico y la subes tú mismo a YubiCloud, se marcará con una advertencia, lo que tendrá consecuencias: los proveedores de servicios podrían desconfiar de dicha clave, y Yubico podría eliminar esas claves secretas en cualquier momento y por prácticamente cualquier motivo.

Si queremos escribir una nueva configuración en la primera ranura de la clave, debemos especificar algunas opciones adicionales. Si deseas subir tu clave a Yubico para autenticarte en sus servidores, recuerda los valores que uses a continuación. Los necesitarás más adelante.

$ ykpersonalize -1 -o fixed=vvhhhrhkhgidic -o uid=deadbeefcafe -a 123456deadcfaebeef65432112345678 -o append-cr

La opción -1 indica a ykpersonalize que utilice la primera configuración. La opción fija especifica el ID público de la YubiKey. Este se denomina «prefijo» más adelante, al subirla. El valor que utilice aquí debe comenzar con «ff» en hexadecimal o «vv» en modhex (consulte más abajo). Yubico aplica esta restricción al intentar subir la clave a sus servidores. El valor de la opción fija puede tener hasta 16 caracteres.

Como parte del OTP, puede especificar un identificador interno para su clave. Esto es lo que hace la opción uid. El valor está en formato hexadecimal simple, no modhex, y tiene de largo ''exactamente'' 12 caracteres.

La opción -a, de nuevo, es la clave AES de 32-byte y append-cr agrega un retorno de carro a mi clave como último carácter.

Al pulsar la tecla <ENTRAR>, el programa ykpersonalize le presentará mis opciones y le pedirá confirmación antes de continuar:

Versión de firmware 2.1.1 Nivel táctil 1795 Secuencia de programa 3 Datos de configuración que será escribita en la configuración de tecla 1:

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

¿Confirmar? (s/n) [n]:

Tras pulsar la tecla 'y', ¡serás capaz de generar códigos OTP con tu clave nueva!

¿Qué es modhex?

Al conectarse, el sistema operativo trata la YubiKey como un teclado USB. Los teclados USB envían códigos de escaneo al sistema operativo, que este interpreta como pulsaciones de teclas. La YubiKey debe evitar cualquier ambigüedad: existen muchos tipos diferentes de distribución de teclado y los códigos de escaneo deben interpretarse como el mismo carácter en todos los equipos que utilizan cualquier distribución de teclado. Para solucionar esto, los desarrolladores de Yubico crearon «modhex», una representación modificada de caracteres hexadecimales que utiliza únicamente caracteres «seguros». Los caracteres «seguros» son aquellos que tienen el mismo código de escaneo en todas las distribuciones de teclado.

Subiendo la clave AES generada en Yubico

Si deseas personalizar la clave AES de tu YubiKey, pero seguir usándola para autenticarte a través de los servidores de Yubico, puedes subirla a través de https://upgrade.yubico.com/getapikey/. Deberás introducir tu dirección de correo-e y la contraseña de un solo uso (OTP) de tu YubiKey.

Actualizar los pines del módulo PIV

El módulo Verificación de Identidad Personal (PIV) almacena claves privadas y los archivos de certificado correspondientes para fines como cifrado, autenticación y firmas. Si tu YubiKey es compatible con esta función, deberás cambiar el PIN, el PUK y la clave de administración.

Establece el PIN.

$ ykman piv access change-pin
Introduzca el PIN actual: 123456
Introduzca el PIN nuevo: ********
Repita para confirmación: ********
PIN nuevo establecido.

Establece el PUK.

$ ykman piv access change-puk
Introduzca el PUK actual: 12345678
Introduzca el PUK nuevo: ********
Repita para confirmación: ********
PUK nuevo establecido.

Actualizar la Clave de Administración.

$ ykman piv access change-management-key --generate --protect
Introduzca la llave de gestión actual [en blanco para utilizar llave predeterminada]:
Introduzca el PIN: ********

Ahora puede utilizar de forma segura el módulo PIV para generar claves privadas y almacenar certificados.

Cambie el PIN del módulo FIDO2

FIDO2 es un estándar de autenticación abierto que abarca sub‐estándares y protocolos para proporcionar métodos de autenticación de dos factores o incluso sin contraseña.

Un caso de uso interesante del módulo FIDO que cabe destacar es el almacenamiento de identidades de clave pública de OpenSSH, que los agentes modernos de OpenSSH pueden reconocer y utilizar de inmediato. Esto hace que las claves SSH sean bastante portátiles.

Si tu llave admite FIDO, cambia su PIN con ykman fido access de esta manera:

$ ykman piv access change-pin
Introduzca el PIN actual: 123456
Introduzca el PIN nuevo: ********
Repita para confirmación: ********
PIN nuevo establecido.

Configurar una contraseña para OATH

La característica OATH proporciona los protocolos de autenticación TOTP y HOTP. Se puede proteger con una frase‐contraseña para acceder y generar códigos OTP. Esto difiere de la función OTP de Yubico, que utiliza un único secreto almacenado en la YubiKey para el sistema de desafío‐respuesta.

Cambia la contraseña OATH por:

$ ykman oath access change
Introduzca la contraseña nueva:
Repítala para confirmación:

Configure su dispositivo para recordar esta contraseña tal que no tenga que re‐introducirla más.

$ ykman oath access remember

Utilizando la YubiKey para autenticar frente a servidores OpenSSH

Utilizando FIFO2 y OpenSSH 8.2+, puede generar llaves OpenSSH que solo sean utilizables si la YubiKey está conectada. Es posible proteger el uso de la clave ya sea presencia o presencia + apunte‐PIN.

Genera una llave pública en cada host intentado para utilizar la llave privada, por tanto un agente OpenSSH pueda descubrirlo:

$ ssh-keygen -t ed25519-sk

Genere la clave pública y almacene su identidad en el módulo FIDO2 para que el par de claves pública-privada sea portátil:

$ ssh-keygen -t ed25519-sk -O resident -O application=ssh:fedora -O verify-required
Las denominadas claves de residente requieren que la clave privada esté protegida por un PIN.

Alternativa para claves sin soporte FIDO2

Si la clave no admite FIDO2, deberá utilizar un método alternativo a través del módulo PIV y PKCS#11.

Crea una clave privada ED25519 dentro del módulo PIV, que requiere introducir un PIN al usarla y siempre requiere pulsar el botón YubiKey:

$ ykman piv keys generate --algorithm ED25519 --pin-policy ONCE --touch-policy ALWAYS 9a public.pem
Introduzca el PIN: ********

La ranura 9a de la llave está dedicada a la autenticación. Existen más ranuras para funciones como el cifrado o la firma.

Cree un certificado en esta misma ranura para la biblioteca PIV/PKCS#11:

$ ykman piv certificates generate --subject "CN=OpenSSH" --hash-algorithm SHA384 9a pubkey.pem
Introduzca el PIN: ********
Toque son su YubiKey…

Ahora, genere una clave pública a partir del certificado X.509 almacenado en la YubiKey. Otras funciones, como las claves residentes, funcionan igual que con el método FIDO2, pero debe agregar la opción adicional que se muestra a continuación.

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

Inicie sesión en los sistemas utilizando esta clave pública:

$ ssh -I /usr/lib/libykcs11.so usuario@remoto.ejemplo.org

El agente ssh también puede cargar claves desde la YubiKey con:

$ ssh -s /usr/lib/libykcs11.so

Uso de YubiKey para autenticarse en sitios web

Desde 2019, se está trabajando en la estandarización del uso de YubiKey en la web. El nuevo estándar se llama WebAuthn y puedes obtener más información aquí: https://www.yubico.com/solutions/webauthn/. Por ahora, la forma más sencilla de ver qué plataformas son compatibles con YubiKey es consultar el catálogo de Yubico.

Como alternativa a Yubico OTP o WebAuthn, que no requieren almacenar credenciales en la YubiKey por defecto, también puedes usar el método TOTP tradicional, como el que se utiliza en la mayoría de los sitios web hoy en día. Existen aplicaciones para ordenador y, al menos, para Android que facilitan su uso. Puedes almacenar hasta 32 credenciales TOTP en una YubiKey 5.

Instala la aplicación de escritorio desde los repositorios oficiales:

$ sudo dnf install -y yubioath-desktop

Agrega una cuenta TOTP con ykman de esta manera:

$ ykman oath accounts add google <TOTP secreto>

Obtén un código TOTP de esta manera:

$ ykman oath accounts code google

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