LUKS and YubiKey: unlocking Linux at boot

An encrypted drive, a hardware key… and an unsuccessful boot

A work computer can be lost or stolen. Encrypting its system volume helps protect data at rest, but leaves a practical question: how should access be authorised during boot? A passphrase provides one answer. A smartcard or YubiKey can add an unlocking method based on a physical device held by the user.

This need led me, through work at ADACIS, to examine unlocking a LUKS volume over PKCS#11. The configuration worked on Fedora, while the same use case ran into difficulties on Debian and Ubuntu with dracut. The obstacle was in the boot environment, before the encrypted root volume could be opened.

On 30 October 2025, I opened dracut issue #1794. A year after it was addressed, this account complements the article published on ADACIS’s blog: understand the technical chain, examine what was actually fixed and identify what to check on a current installation.

The outcome to validate goes beyond “my key is detected”. It is “my key can unlock the intended volume in the environment actually used during boot”.

The security objective: protecting a lost or stolen workstation

The main reference is measure 31 of ANSSI’s IT hygiene guide, concerning encryption of sensitive data on equipment that may be lost. LUKS provides encryption; the card controls access to the unlocking secret. Measure 31, p. 42, in French.

A card requiring a PIN also contributes to measure 13 on strong authentication, subject to checking both factors and alternative access routes. Measure 13, p. 19.

What LUKS does, and what the YubiKey does

First, we need to distinguish data encryption from the method used to access keys. LUKS organises the volume’s metadata and keyslots. Encryption and decryption of blocks take place on the computer, through Linux’s storage stack and dm-crypt. The USB token does not process every disk read and write. Linux kernel documentation: dm-crypt.

In the workflow discussed here, the YubiKey provides smartcard functionality exposed through PKCS#11, a standard interface for accessing cryptographic objects and operations. An RSA or EC key pair must already be available on the token, along with the objects needed for discovery. systemd-cryptenroll can associate that token with a LUKS2 volume.

In the RSA case, the token performs the private-key operation that recovers the secret used for unlocking. The hardware private key does not need to be exported. However, the recovered secret is used by the system: this does not mean every secret remains inside the device at all times. systemd PKCS#11 enrolment.

The word YubiKey alone does not describe the architecture: one device may expose several applications. PIV/PKCS#11, examined here, and FIDO2 are separate workflows. The 73pcsc bug must not be generalised to FIDO2 unlocking.

Native support that extends beyond YubiKey

This workflow uses features integrated into the Linux stack: dm-crypt/LUKS for the drive, systemd-cryptenroll for enrolment and systemd-cryptsetup for unlocking. PKCS#11 support in systemd-cryptenroll dates back to systemd 248. Here, “native” means these components implement the mechanism; packages, configuration and the boot image still need preparing for the chosen distribution. systemd-cryptenroll manual.

This moves us beyond the more involved setups that added boot scripts to turn a token response into a LUKS secret. The historical yubikey-luks project, for example, uses a keyscript and YubiKey challenge-response mode. That mechanism belongs to its OTP application and should not be confused with U2F. Today, FIDO2 also has native systemd support, using a token with hmac-secret. A particular benefit of the PKCS#11 workflow examined here is reusing an existing smartcard and certificate infrastructure. yubikey-luks project and systemd’s supported modes.

YubiKey is therefore one hardware example, rather than an exclusive dependency. Other certificate-bearing smartcards and tokens can serve this purpose, if their PKCS#11 module can locate the certificate or public key and perform the unlocking operations using the private key retained inside the device. OpenSC includes a driver for several Gemalto/Thales IDPrime models, opening the possibility of reusing existing corporate cards. OpenSC IDPrime driver.

A certificate alone does not establish universal compatibility. Validate the card model, reader, middleware, algorithms and permitted private-key operations: a card restricted to signatures may not allow the required operation. These components must also work inside the initramfs. That final condition is precisely what explains the cross-distribution bug.

Before the complete system, there is the initramfs

To open an encrypted root volume, Linux needs an initial environment that does not yet depend on that root. This is the purpose of the initramfs: an image containing the tools, libraries, drivers and configuration required for this boot stage. dracut builds the image from modules and the host’s configuration.

Installing OpenSC in the main system therefore does not guarantee its inclusion in that image. The hardware may work once the session is running, while the pre-boot software stack is incomplete. dracut documentation.

From boot to an open volume

Load the initial environmentThe kernel starts the initramfs before the encrypted root is accessible.kernel → initramfs
Make the smartcard usableThe PKCS#11 stack and its dependencies must be included in this image.p11-kit · OpenSC · pcscd
Authorise the private-key operationThe YubiKey performs the operation; PIN requirements depend on its policy.PKCS#11 ↔ YubiKey
Open the LUKS2 volumeThe system gains access to the volume and continues booting from the root.systemd-cryptsetup → dm-crypt

Conceptual diagram: the hardware token participates in unlocking; block encryption remains on the computer.

Within this environment, systemd-cryptsetup handles opening the volume. For the smartcard workflow, it needs a consistent software stack: p11-kit for module discovery, OpenSC for the PKCS#11 interface, and pcscd, with the required drivers, for card access. OpenSC documents its role as an interface to cryptographic smartcards. OpenSC overview and systemd-cryptsetup service.

The bug: three differences between distributions

The original report concerned dracut 108, with a working setup on Fedora 42 and a reported failure on Ubuntu 25.10, alongside the Debian/Ubuntu portability problems described in the issue. These are the references for the 2025 investigation, rather than a claim about every current installation.

Three discrepancies emerged from examining 73pcsc:

Component	Assumption or omission in the affected module	Requirement identified on Debian/Ubuntu
p11-kit declaration	Looked for `opensc.module`	Also handle `opensc-pkcs11.module`
OpenSC libraries	Incomplete inclusion in the reported case	Add the `libeac.so*` family
Local configuration	Used `/etc/opensc.conf`	Also consider `/etc/opensc/opensc.conf`

Their impact is greater than the size of the changes suggests: a file omitted when the image is built is also missing when the system tries to use the smartcard. Issue #1794 and its discussion.

Same hardware, two different environments

After boot

Main system

Packages and dependencies installed
OpenSC configuration available
Token usable in the session

Works in this context

Before opening the root

Incomplete initramfs

Missing or unsuitable p11-kit declaration
Library omitted from the image
Configuration path not handled

PKCS#11 workflow fails

Illustration of the historical diagnosis, not a screenshot or a finding about every current version.

This diagnosis helps avoid a misleading assumption: detecting a USB device does not prove that the application can use it. Between the physical token and LUKS unlocking, a missing library or configuration file can interrupt the workflow.

From the report to the integrated fix

The contribution followed the usual open-source process: a reproduced case, discussion with maintainers and an integrated change. PR #1804, submitted by jozzsi, led to commit 1575aea44209d56ca0e80ca287b8f00f739e332d being integrated on 31 October 2025. The issue was closed as completed that day. PR #1804 and integrated commit.

Here are three excerpts from the accepted change to modules.d/73pcsc/module-setup.sh. They explain the fix; they are not a patch to apply blindly to a recent version.

1. Include both p11-kit module names

     inst_multiple -o \
         pcscd \
-        /usr/share/p11-kit/modules/opensc.module
+        /usr/share/p11-kit/modules/opensc.module \
+        /usr/share/p11-kit/modules/opensc-pkcs11.module

The original name remains supported, and the Debian/Ubuntu name is added. The -o option makes installation of these files optional: a missing path on one distribution does not, on its own, prevent image generation.

2. Include the missing library

+        {"tls/$_arch/",tls/,"$_arch/",}"libeac.so*" \
         {"tls/$_arch/",tls/,"$_arch/",}"libpcsclite.so.*" \

This Bash expression covers several library-path variants. Its purpose is to bring the dependency into the initramfs. Installing its package in the main system without rebuilding the image would not fix an image that had already been generated.

3. Support the second configuration path

     if [[ $hostonly ]]; then
         inst_multiple -H -o \
             /etc/opensc.conf \
+            /etc/opensc/opensc.conf \
             "/etc/reader.conf.d/*"

The addition is inside the host-only block, which includes local configuration in an image tailored to the machine. This condition is part of the fix: describing the copy as unconditional would be inaccurate.

Excerpts from the cited commit, in a dracut source file licensed under GPL-2.0-or-later. The paths and $_arch variable correspond to that historical revision.

The final fix therefore differs from some of the initial proposals: it keeps two explicit declarations instead of a wildcard for their names, and the added library family is libeac.so*. That distinction matters when explaining what upstream actually accepted.

Checking a current installation in the right order

An upstream fix does not prove that an installed package contains it. Distributions ship their own versions and may backport changes. The appropriate approach is to identify the package, read its history and examine the boot image that will actually be used.

Identify the volume and installed stack

The following commands are diagnostic; they do not encrypt or modify a volume:

lsblk -o NAME,TYPE,FSTYPE,UUID,MOUNTPOINTS
systemd --version
dracut --version

# Discover usable PKCS#11 tokens without enrolling one.
systemd-cryptenroll --pkcs11-token-uri=list

The last command examines tokens from the running system. A positive result validates that part of the workflow, rather than the initramfs. A missing dracut command is also useful information: first establish which image generator the machine actually uses.

Inspect the image that will boot

With lsinitrd, provided by dracut, we can distinguish included modules from embedded files. Replace the path below with the image corresponding to the kernel being tested:

INITRAMFS="/path/to/initramfs-image"

sudo lsinitrd -m "$INITRAMFS"
sudo lsinitrd "$INITRAMFS" |
  grep -E 'pcscd|opensc.*\.module|opensc-pkcs11\.so|libeac\.so|opensc\.conf'

A common Fedora path is /boot/initramfs-<kernel-version>.img. On Debian/Ubuntu, /boot/initrd.img-<kernel-version> is common. The filename alone does not identify its generator. lsinitrd manual.

The filter provides clues, rather than complete proof: check the right paths, the installed version’s dependencies and whether the stack actually loads. Similarly, dracut --list-modules lists available modules, whereas lsinitrd -m examines those in the selected image.

Separate enrolment from boot configuration

For an existing LUKS2 volume, with a correctly provisioned smartcard and a verified recovery method, enrolment can take this form:

# Adapt this example to the identified LUKS container in a test environment.
sudo systemd-cryptenroll \
  --pkcs11-token-uri=auto \
  /dev/disk/by-uuid/LUKS_CONTAINER_UUID

This command adds an access method; it does not create the key pair on the smartcard or turn an unencrypted drive into a LUKS2 volume. auto assumes that a single suitable token can be selected; otherwise, use an explicit PKCS#11 URI. systemd-cryptenroll documentation.

Boot configuration must then request this unlocking method. A schematic /etc/crypttab entry is:

cryptroot UUID=LUKS_CONTAINER_UUID none luks,pkcs11-uri=auto

cryptroot is an example name. Preserve the mapping name and options required by the existing installation, then regenerate the image using the distribution’s tool and procedure. A correct crypttab entry in the main system does not guarantee that the image already in /boot has been updated. crypttab format and options.

Is a hardware token enough to claim MFA?

The device provides a possession factor. A PIN required by the smartcard can add a knowledge factor. However, the policy actually enforced must be checked: PIN and touch requirements depend on the device, its application and its configuration. Touching a key confirms physical presence; the gesture is not itself an additional secret. Yubico PIN and touch policies.

Other unlocking methods also matter. A passphrase retained in another keyslot remains an alternative access route: adding the token does not automatically require “smartcard + PIN” for every access. That recovery route serves an operational purpose, but belongs in the security model.

Encryption at rest does not guarantee the integrity of the boot chain either. Trust in firmware, the bootloader, kernel and initramfs needs separate consideration, including an appropriate Secure Boot architecture. After the volume is opened, removing the YubiKey does not automatically close it or protect against an already compromised system.

What I would validate before deployment

The decisive check remains a controlled reboot on a validation machine. I would include at least these scenarios:

Key present and correct PIN: the intended volume opens and the system continues booting.
Key absent or incorrect PIN: behaviour matches the chosen policy, without repeated attempts that might lock the smartcard.
Lost or failed key: the recovery procedure allows the system to boot, with controlled access to recovery secrets.
Kernel or package update: the new image still contains the required components and the workflow is retested.

A tested recovery method and a protected LUKS header backup avoid reliance on a single device or image. The backup retains material used to access the data and must be treated as sensitive. Header backup manual. Incident evidence should distinguish USB, PC/SC, PKCS#11 and volume activation: “it will not boot” is a symptom, rather than a diagnosis.

The commands in this article were checked against the cited documentation. This is not a report of a new boot test performed on every current version of Fedora, Debian and Ubuntu.

From encryption to compliance: what can be demonstrated

ANSSI’s recommendations translate the security objective into verifiable criteria. Two publications usefully extend its hygiene guide:

The Recommendations on multifactor authentication and passwords (2021), particularly R1 on MFA and R3 on risk analysis, help define the “smartcard + PIN” policy, assignment of devices and treatment of recovery access. ANSSI guide, in French.
The Recommendations on digital nomadism, version 2.0 (2023), go further: R9 calls for encryption, a TPM and boot-chain checks; R9+ adds a smartcard and PIN. This article’s PKCS#11 workflow does not demonstrate that combination. Independently enrolling a TPM and a card creates alternative access routes, rather than requiring their joint use. ANSSI guide, § 3.3.4, in French.

On the regulatory side, GDPR Article 32(1)(a) identifies encryption among security measures appropriate to the risk to personal data. An encrypted work computer with controlled hardware-based access can therefore make a practical contribution to meeting this security obligation. The risk assessment, chosen configuration and test results should explain why that protection fits the processing concerned. Article 32, published by CNIL.

Compliance involves the technical measures and their operation: access management, recovery, backups and regular checks. The hygiene guide provides recommendations; the GDPR is binding within its scope. Combining this software and hardware also does not automatically confer ANSSI qualification or approval: where a deployment requires that status, select an appropriately recognised product and follow its permitted scope of use.

An alternative to paid products on Windows

This integration also changes the economic comparison. Linux offers an encryption and smartcard-unlocking chain based on free software, without an additional per-device encryption licence. In my view, it directly competes with paid proprietary products offering pre-boot authentication on Windows for this specific requirement. Symantec Endpoint Encryption, for example, documents the use of PIV cards and readers during boot. Broadcom documentation.

The comparison needs a precise scope: Windows also has a native solution, BitLocker, available according to edition and licensing. Microsoft states that BitLocker does not support smartcards for pre-boot authentication; using them with data volumes is a separate case. The workflow being compared here is specifically “system volume + smartcard at boot”. BitLocker FAQ on smartcard pre-boot authentication.

A commercial product’s cost can also cover an administration console, deployment, centralised recovery, support and compliance evidence. LUKS and systemd provide the technical mechanism; those operational services still need organising. Licence savings should therefore be assessed against the full cost of managing the fleet.

Why YubiKey remains a credible economical choice

Within this open architecture, I consider a PIV-capable YubiKey an economical and reliable option, subject to validation of the model and boot workflow. Its USB form factor avoids a separate card reader, and its documented support allows deployment on a maintained software stack. Budget for provisioning, recovery and replacement. The YubiKey 5 series supports PIV; a device limited to FIDO/U2F does not support this PKCS#11 workflow. Yubico PIV documentation.

Adoption extends beyond Linux workstations. On 30 April 2026, OpenAI and Yubico announced a partnership to protect ChatGPT accounts with hardware-backed passkeys through Advanced Account Security. This concerns FIDO/passkeys, a separate use case from unlocking LUKS through PIV. Yubico’s official announcement.

The announcement was also followed by strong market interest: on 4 May 2026, Omni Ekonomi reported Yubico shares rising approximately 15% during trading, in a context combining the partnership and an SEB analysis of security needs arising from AI. This is a commercial signal; pre-boot reliability is assessed through the technical checks described above. 4 May report.

Linux and sovereignty: part of a national strategy

Retaining hardware-based unlocking on Linux connects to a wider objective: reducing the French State’s digital dependencies. On 8 April 2026, DINUM announced its own transition from Windows to Linux workstations, through a sovereignty initiative involving DGE, ANSSI and DAE. Each ministry must also formalise a plan to reduce dependencies outside Europe. The announcement therefore covers DINUM’s workstations and a wider interministerial planning effort. Official announcement, in French.

In that context, making LUKS, systemd and the smartcard stack reliable removes a concrete migration obstacle: changing operating systems while retaining a physical access-control device. Free software and standard interfaces provide more scope to audit, maintain and replace components. Sovereignty also depends on hardware suppliers, support and available skills; an open architecture allows those choices to be addressed without tying it to a single token brand.

My conclusion

The central lesson is straightforward: reliable hardware-based unlocking depends on the whole boot chain. A compatible token and a correctly enrolled volume are insufficient if the environment loaded before the encrypted root lacks the right files.

The value of contributing to dracut was to fix the integration at its source, rather than leave each installation maintaining its own library copies. That also makes the work useful beyond the YubiKey in the initial case: it addresses integration of the smartcard stack, subject to compatibility requirements.

For me, the system’s value rests on three outcomes: normal boot works, failure can be understood and recovery remains possible. Once those conditions are met, this native, open stack provides a practical alternative for protecting a Linux fleet, contributing to applicable security requirements and supporting a digital-sovereignty strategy. Together, they turn a technical demonstration into protection that can be operated day to day.

Sources and milestones

Written on 3 November 2026, using the historical report, the integrated fix and the documentation consulted. Adapt commands and paths to the installed versions.

In this article