Implement support for Yubikeys and potential other tokens via wireless NFC using smartcard readers#6766
Conversation
* Allow for multiple vendor ID's to be checked at once. This allows for the use of one tracking index, streamlining KPXC code. * Remove support for libusb 0.x on Linux * Better handling of USB errors during initial key query. Output warnings to console.
|
The CI build on Linux probably fails due to the missing As for the code format check I have no idea. I ran |
|
Please rebase this onto my yubikey pr |
|
Also, holy shit you are awesome! |
I assume you mean #6654 ?
I am glad you like it, it was quite a challenge to get this running smoothly on all three systems. |
Yes, that will make this easier to merge once we merge that one first.
That is definitely a challenge for a lot of our integrations, very tough project to make this work without a hitch! |
This requires a new library dependency: PCSC. The PCSC library provides methods to access smartcards. On Linux, the third-party pcsc-lite package is used. On Windows, the native Windows API (Winscard.dll) is used. On Mac OSX, the native OSX API (framework-PCSC) is used.
The main YubiKey file now acts as a gateway to multiple interfaces, which each implement YubiKeyInterface.
Since the Yubikey can now be a wireless token as well, the verb "plug in" was replaces with a more generic "interface with". This shall indicate that the user has to present their token to the reader, or plug it in via USB.
This new interface uses the PC/SC protocol and API instead of the USB protocol via ykpers. Many YubiKeys expose their functionality as a CCID device, which can be interfaced with using PC/SC. This is especially useful for NFC-only or NFC-capable Yubikeys, when they are used together with a PC/SC compliant NFC reader device. Essentially, this implementation does the same as the ykdroid module for Keepass2Android: It provides a way to wirelessly (depending on the reader) interface a YubiKey or any key which implements the Yubikey challenge-response HMAC-SHA1 protocol. Although many (not all) Yubikeys expose their CCID functionality over their own USB connection as well, the HMAC-SHA1 functionality is often locked in this mode, as it requires eg. a touch on the gold button. When accessing the CCID functionality wirelessly via NFC (like this code can do using a reader), then the user interaction is to present the key to the reader, just like you would tap the key against your phone when using ykdroid. This implementation has been tested on Linux using pcsc-lite, Windows using the native Winscard.dll library, and Mac OSX using the native PCSC-framework library.
4686430 to
9c44cf7
Compare
|
Alright, I rebased the feature branch onto your PR. Everything still works according to my tests.
In addition, I added a small fix for Windows, which enables USB hotplugging for reader devices. I also clarified the YubiKey security timeout flow. |
|
If you do not have a NFC Yubikey or a NFC PC/SC card reader, I added instructions on how to emulate the PC/SC HMAC-SHA1 functionality of a Yubikey completely in software on Linux: https://github.com/StarGate01/vk-ykhmac#readme . |
|
Excellent, we'll merge my pr first then rebase yours onto develop |
9e88fc4 to
7cb8265
Compare
7cb8265 to
7db9e3a
Compare
|
Should I rebase this PR on the current state of |
|
How'd this get closed, stupid github. Yes please rebase. I think this closed cause the branch was deleted, once you rebase and set this up to track develop then I can reopen it. |
This fixes #4090 and arekinath/YkOtpApplet#3 , and might fix #6439 . It also potentially provides a base for #255 .
Rationale
I want to use my Yubikeys with KeePassXC not (only) by plugging them in via USB, but also by wirelessly presenting them to a NFC reader which is connected via USB or built-into my computer - just like I do on my phone.
Eventually, other hardware tokens which do not have a USB interface at all but implement the wireless protocol will be supported automatically as well. Examples include eg. the Vivokey or any smartcard running vk-ykhmac.
Screenshots
Explanation of changes
This new interface uses the PC/SC protocol and API, instead of the USB protocol via the
ykperslibrary. Both interfaces can be used in parallel and the same key can be used on both interfaces without reprogramming it.Many YubiKeys expose their functionality as a smartcard / CCID device, which can be interfaced with using PC/SC. This is especially useful for NFC-only or NFC-capable Yubikeys, when they are used together with a PC/SC compliant NFC reader device.
Essentially, this implementation does the same as the ykdroid module for Keepass2Android:
It provides a way to wirelessly (depending on the reader) interface a YubiKey or any key which implements the Yubikey challenge-response HMAC-SHA1 protocol.
Although many (not all) Yubikeys expose their CCID functionality over their own USB connection as well, the HMAC-SHA1 functionality is often locked in this mode, as it requires eg. a touch on the gold button. When accessing the smartcard functionality wirelessly via NFC (like this code can do using a reader), then the user interaction is to present the key to the reader, just like you would tap the key against your phone when using
ykdroid. A continuously presented key eventually times out due to security concerns.This implementation has been tested on Linux using
pcsc-lite, Windows using the nativeWinscard.dlllibrary, and Mac OSX using the nativePCSC-framework(which is a port ofpcsc-liteby Apple) library.Changes to the build system
Since this feature requires the PCSC API libraries for each OS, the cmake configuration has been changed to automatically find and link the correct one.
A new build flag (
-DWITH_XC_YUBIKEY_PCSC=[ON|OFF], requires-DWITH_XC_YUBIKEY=ON, default:OFF, but included by-DWITH_XC_ALL=ON) can be used to control whether the new interface is compiled in. If this ifOFF, the functionality remains unchanged, only the existing USB interface is enabled, and no PCSC library is required.Package maintainers on Linux have to add a dependency on
pcsc-liteif they want to include this feature.Smaller changes
Since the Yubikey can now be a wireless token as well, the verb "plug in" was replaces with a more generic "interface with". This shall indicate that the user has to present their token to the reader, or plug it in via USB.
The hardware key selection menu in the UI now additionally displays how a token is connected (USB or PCSC) and its firmware version.
A sample "third-party" hardware token has been added. This is mainly for future developers to be used as a reference for other smartcards.
Testing strategy
The new interface has been compiled and tested successfully on Linux x64 5.4.131-1-MANJARO, Windows 10 x64 21H1, and Mac OSX x64 18.2.0 Mojave (using VirtualBox) using the documented build tools.
The hardware keys used for testing were:
In general, all PC/SC compliant CCID devices which implement the Yubikey HMAC-SHA1 challenge-response protocol should work.
The readers used for testing were:
In general, all PC/SC compliant NFC-capable smartcard readers with CCID / PC/SC driver support for the target OS should work.
The keys were programmed with the same HMAC-SHA1 secret, and verified to be able to generate a valid key to unlock the database in all modes and slot configurations.
Type of change
Workflow note
I realize this is a rather large PR, and especially since this is my first one to this project I am happy to receive any feedback concerning conventions, methodology or anything else. If there are questions or concerns regarding the implementation, I am willing to adjust the code if needed.
If there are things that should be changed or any mistakes, please point them out. Although I did my best to verify and test on all systems using all the hardware I have available, some things might have slipped though.
If this is something you do not want to add at all, I would like to discuss why and what would have to be changed or implemented instead.
Sources and further reading