keepassx/keepassx — pull request #52 by kylemanna (2014-05-26 18:29:11+00:00)
Title: RFC: Add Yubikey HMAC-SHA1 Challenge-Response

Overview
--------

This pull request adds support for [YubiKey](https://yubico.com), a USB authentication device commonly used for 2FA. Support is added by configuring a YubiKey slot to operate in HMAC-SHA1 challenge-response mode. The mechanism works by submitting the database master seed as a challenge to the YubiKey which replies with a HMAC-SHA1 cryptographic hash. The resultant hash is then hashed with the other keys (password, keyfile) to generate the final key used to encrypt the database.

I have uploaded a few [screenshots to imgur](https://imgur.com/a/NbtBf).

Details
-------

* Breaks the ability to open the KeePass2 database by anything other then KeePassX with YubiKey support. Perhaps KeePass2 could open it with a plugin, but I didn't look at it.
* Implemented using YubiKey HMAC-SHA1 configuration and operates completely offline.
* The master seed is used as the challenge and changes on every write to help partially combat replay attacks as it's regenerated every time the database is saved.
* YubiKey User Input Mode can be configured in a blocking or non-blocking mode.
* Non-blocking mode is preferred such that the challenge-response can quickly be issued and returned despite being slightly less secure due to lack of user input.
* Blocking mode works, but doesn't provide feedback to the user, so the UI appears to hang even though it's waiting. I preferred simplicity for the initial code.
* Upon generation of the HMAC key, it can be saved and cloned to other YubiKey devices to prevent loss of database access to loss or destruction of the YubiKey hardware. This is highly recommended.
* Only supports the first detected YubiKey Plugged in, but does enumerate both configuration slots on the device. I only have one YubiKey and can't test multiple (yet).
* The `libyubikey` and `ykpers-1` libraries are necessary for support. These libraries are detected at compile time to enable support and necessary at run-time.
* Tested on Arch Linux and Mac OS X Mavericks with and without YubiKey support
* Arch Linux via AUR:
* libyubikey: 1.11-1
* yubico-c-client-git: 2.12.r2.g539af75-1 and 2.12.r3.g262a19c-1
* yubikey-personalization-git: 1.14.2.r5.ga7392f0-1 and 1.15.1.r10.g52890f6-1
* Mac OS X Mavericks via Homebrew:
* libyubikey: stable 1.11
* ykpers: stable 1.15.1
* Test hardware is a YubiKey Standard with firmware version 2.2.3.
* Adds challenge-response combo box to support other mechanisms in the future
* Can be disabled explicitly at compile time with `cmake -DCMAKE_DISABLE_FIND_PACKAGE_YubiKey=TRUE`

Quick Start Guide
-----------------

1. Install necessary libraries to appease KeePassX's CMake configuration step

-- The following OPTIONAL packages have been found:
* YubiKey

2. Install [yubikey-personalization-gui](https://github.com/Yubico/yubikey-personalization-gui) and configure slot 2 for HMAC-SHA1 challenge-response. Be sure to write the configuration. Optionally it can be programmed via the command line.
3. Start up KeePassX with the YubiKey inserted and the challenge-response form of the DatabaseOpenWidget ChangeMasterKeyWidget should enable themselves asynchronously listing the inserted YubiKey. Review [screenshots on imgur](https://imgur.com/a/NbtBf) for the configuration tool.

Upstream / Reference
--------------------

* [yubico open source software](https://www.yubico.com/develop/open-source-software/)
* [libyubikey](https://github.com/Yubico/yubico-c)
* [yubico-c-client](https://github.com/Yubico/yubico-c-client)
* [yubikey-personalization-gui](https://github.com/Yubico/yubikey-personalization-gui)