TKey-LUKS: Hardware-Based LUKS Unlock with Tillitis TKey

Unlock LUKS encrypted root partitions securely during boot using the Tillitis TKey hardware security key. This innovative project ensures that the TKey device is physically present at boot time, providing a dynamic method to derive the LUKS encryption key through cryptographic processes performed by the TKey.

Overview

The TKey-LUKS project offers a robust solution for securing LUKS encrypted root partitions, enhancing overall system security and integrity.

Key Features

• 🔐 Hardware-Based Security: Derives LUKS keys from TKey device secrets, ensuring secure access.
• 🔑 Improved USS Derivation: Enhances User Supplied Secret (USS) generation via PBKDF2, without ever storing sensitive information on disk.
• 🚀 Boot Integration: Simplified integration with initramfs for a seamless user experience.
• 🔧 Static Binary: Removes dependencies in the initramfs environment, streamlining deployment.
• 🧪 Test Environment: Comprehensive testing scripts for hardware and image-based scenarios.
• 📦 Easy Installation: Automated scripts to facilitate straightforward installation.
• 🔄 Fallback Support: Optional password fallback mechanism for additional access security.
• ✅ Conventional Commits: Maintains strict commit standards through Continuous Integration (CI) and git hooks.

Security Highlights

The project has modernized how USS is derived, no longer writing any sensitive information to disk.

• ✅ User Supplied Secrets (USS) are now generated from user passwords dynamically, enhancing security against potential data breaches.
• ✅ Each installation generates a unique USS utilizing machine-id salt, making reproduction of secrets exceedingly difficult.
• ✅ The established KDF with 100,000 iterations strengthens protection against brute-force attacks.

This improved method prevents extractable secrets from residing in boot partitions, maintaining robust security even against physical attacks. For an in-depth analysis of security protocols, visit SECURITY.md.

Project Status

As of v1.1.1, the project addresses salt availability to fortify USS derivation. Key updates:

• ✅ Machine-id Enhancement: Copies machine-id to initramfs for stable USS performance.
• ✅ Verification Tool: Introduced a script for checking salt availability post-installation.
• ✅ Documentation: Added detailed troubleshooting guides for USS issues.

Tested Systems

TKey-LUKS has been successfully validated on:

• Ubuntu 24.04 Desktop with NVMe encrypted partitions, achieving a boot-time of approximately 33 seconds (including required physical interaction with TKey).

Architecture

The system features three essential components:

1. Device Application: Executes on TKey and performs critical cryptographic operations.
2. Client Application: Operates within initramfs, handling communication with the TKey.
3. Initramfs Hooks: Integration points within the boot process ensure smooth operations.

Documentation and Support

• Setup Guide
• Testing Procedures
• Security Considerations
• Initramfs Integration Details

Conclusion

TKey-LUKS provides a robust and secure method for unlocking LUKS encrypted partitions at boot. This project significantly enhances the security posture for Linux-based systems, safeguarding against unauthorized access and potential physical attacks. For those looking to increase encryption security, TKey-LUKS presents an effective and innovative solution.

Contributions to the project are welcome, adhering to the Conventional Commits specification to maintain clarity and quality in code management.