Copyright © 2011-2015 Dominik Reichl. Distributed under the terms of the GNU General Public License v2.

OtpKeyProv is a key provider based on one-time passwords. After protecting your database using this plugin, you need to generate and enter one-time passwords in order to open your database.

Supported Generator Tokens

All generator tokens that follow the OATH HOTP standard (RFC 4226) are supported.

Especially, the plugin has been tested successfully with the following generator tokens:

• YubiKey
• sCrib

Installing the Plugin

In order to install OtpKeyProv, copy the files OtpKeyProv.plgx and OtpKeyProv_ReadMe.html into the KeePass application directory (where KeePass.exe is), and restart KeePass.

If you wish to uninstall the plugin in the future, simply delete these two files.

Protecting a Database

After installing OtpKeyProv, you can set up your database to require one-time passwords for opening. To do this, open your database and go 'File' -> 'Change Master Key'. Check 'Key file/provider', select 'One-Time Passwords (OATH HOTP)' in the combo box, and click the [OK] button (do not click the [Create] or [Browse] buttons; these are for key files only). An OTP configuration dialog is now displayed, in which need to provide the generator token's secret key, the current counter, and specify various options; for details see below. When you've filled in everything, click [OK]. After saving the database file, your database now requires entering one-time passwords for opening.

Length of generated OTPs. Here you need to specify of how many characters the OTPs consist that the token generates. According to the OATH HOTP standard, the length must be 6, 7 or 8. If the token allows you to configure the length, it is recommended to choose the maximum length for highest security.

Generator token secret key and counter. Here you need to provide the current secret key and the counter (which is also called 'moving factor') of the generator token. These values can be entered in different formats: Hex, Base64, Base32, UTF-8 and Dec. If you don't know in which format the token displays the values, here are some rules of thumb:

• If the value consists only of digits (0-9), the format likely is Dec.
• If the value consists of digits (0-9) and the letters A-F, the format most likely is Hex.
• If the value consists of 0-9, A-Z, a-z, '+', '/' and '=', the format might be Base64.
• If the value consists of 2-7, A-Z and '=', the format might be Base32.
• If none of the above matches, try the UTF-8 format.

Number of required OTPs. Here you can specify the number of OTPs that need to be entered in order to open the database. The more OTPs, the more secure the database is. See the section 'Security' below for details.

Look-ahead count. OtpKeyProv supports look-ahead windows. When a number n is specified as look-ahead count, n OTPs may be skipped and opening will still work. For example, if the OTP sequence is A B C D E F G H (where each letter represents a multi-digit OTP), 4 OTPs are required and the look-ahead count is 2, then all of the following OTP sequences will open the database: A B C D, B C D E and C D E F.

The default look-ahead count is 0, i.e. only exactly one OTP sequence will work. The higher the look-ahead count is, the less secure the protection of the database is.

Generator token configuration.

• If your generator token has an option to send an Enter keypress at the end, you should disable this behavior (otherwise the OtpKeyProv dialog closes prematurely with [OK]).
• If your generator token has an option to send an OATH Token Identifier before the actual OTP, this should be disabled (i.e. only the OTP should be sent).

Opening a Database

In the master key prompt dialog, select 'One-Time Passwords (OATH HOTP)' in the combo box and click [OK]. You're then prompted for the OTP information. There are two modes:

• Standard mode. Generate and enter as many OTPs as the dialog requests.
• Recovery mode. If you can't open the database using OTPs anymore (e.g. because the generator token and the database are out of sync), you can alternatively enter the generator token's secret key to open the file. After opening the database, go 'File' -> 'Change Master Key' to synchronize the generator token and the database again.

Automation. By default, the KeePass option 'Remember key sources (key file paths, provider names, ...)' is enabled, so the next time you want to open the database the OTP key provider in the combo box will be preselected and you just need to click [OK] (in case you're not combining the OTP lock with a master password or the Windows user account).

If you don't even want to click the [OK] button (i.e. you want to see the OTP prompt immediately), you can tell KeePass that you're just using the OTP lock by passing an appropriate command line option. Create a shortcut to KeePass.exe or a batch file running KeePass with the following arguments:

"C:\Path\To\Database.kdbx" -keyfile:"One-Time Passwords (OATH HOTP)"

More information can be found in the KeePass Command Line Options documentation.

Options. On the 'Options' tab of the dialog, the following options are available:

• Auto-Accept. If this option is enabled, the dialog is closed automatically with [OK] when all required OTPs have been entered.
• Auto-Tab. If this option is enabled, the focus is automatically switched to the next OTP input box when an OTP with the required length has been entered into the current box. If your OTP generator token inputs the OTPs for you and simulates a tab keypress at the end (like e.g. sCribs do by default), you should not enable this option (otherwise the focus is moved twice, skipping one OTP input box).

Security

The more OTPs are required to open the database, the more secure it is. The minimum number is 3 (everything below 3 is completely insecure; the database would be crackable within seconds), the maximum number is 6.

The following table summarizes how secure databases are that are protected using OTPs. We assume no other user keys (master password, Windows user account, ...) are used.

The column #OTPs lists the number of one-time passwords required to open a database. The key size can be computed as log₂(10^{OTP Length ⋅ #OTPs}) = OTP Length ⋅ #OTPs ⋅ log₂(10) ≈ OTP Length ⋅ #OTPs ⋅ 3.322.

The table assumes a look-ahead count of 0. If a look-ahead count n ≥ 1 is specified, the chance that a brute-force attack enumerating OTPs succeeds is at least n+1 times higher. Thus, it is recommended to keep the look-ahead count as low as possible, ideally 0 (which is the default).

Acknowledgements

• Thanks to pgbrandolin for creating and publishing the nice crypto chip icon as public domain on the Open Clipart Library.
• Thanks to Dan Cvrcek for providing an sCrib generator token for testing the plugin.
• Thanks to Karl Lohnauer for providing a YubiKey generator token for testing the plugin.

Version History

• 2.4
  • When saving a database, the OTP info file is now updated, if necessary.
  • Increased maximum look-ahead count to 40.
• 2.3
  • Converted the crypto chip PNG image as a workaround for a problem in Cairo/LibPNG on Unix-like systems.
• 2.2
  • If the OTP info file cannot be loaded, OtpKeyProv now shows the OTP prompt dialog with the recovery tab page being selected by default.
• 2.1
  • Updated plugin for KeePass 2.20 and higher.
• 2.0
  • Added look-ahead window support.
• 1.3
  • Added support for hex strings containing spaces.
  • Added YubiKey to the list of tested and supported generator tokens.
  • Added generator token configuration hints to the documentation.
• 1.2
  • Added support for Base32-encoded keys and counters.
• 1.1
  • Added support for entering OTPs on the secure desktop.
  • Improved state updating when changing the secret/counter format in the OTP key creation dialog.
• 1.0
  • Initial release.

Links

Latest version of OtpKeyProv:
http://keepass.info/plugins.html#otpkeyprov

Support:
https://sourceforge.net/p/keepass/discussion/329221/

Feature Requests & Bug Reports:
https://sourceforge.net/p/keepass/discussion/329220/

Donations:
http://keepass.info/donate.html