Home

Awesome

Main workflow

*** KeePassNatMsg is in maintenance only mode ***

I don't personally use this plugin anymore, therefore it is currently in maintenance mode, which means I will fix critical bugs, and will still accept PR's. I'm also open to passing this project on to a new maintainer, see the relevant discussion topic.

KeePassNatMsg

is a plugin for KeePass 2.x and provides a secure means of exposing KeePass credentials to a browser via Native Messaging.

It is based on KeePassHttp.

This plugin is primarily intended for use with the keepassxc-browser browser extension.

Features

System requirements

Installation

  1. Download the latest KeePassNatMsg release
  2. Unzip it into the KeePass\Plugins directory
    • default directory in Ubuntu14.04: /usr/lib/keepass2/
    • default directory in Arch: /usr/share/keepass
  3. On linux systems you maybe need to install mono-complete: $ apt-get install mono-complete (in Debian it should be enough to install the packages libmono-system-runtime-serialization4.0-cil and libmono-posix2.0-cil)
  1. Restart KeePass
  2. Go to Tools -> KeePassNatMsg Options
  3. Click on "Install/Update Native Messaging Host", wait for message telling you it was installed.
  4. Install the KeePassXC-Browser extension for your browser, and Connect to the database from within the extension.

Chocolatey 📦

Or you can use Chocolatey to install it in a more automated manner:

choco install keepass-plugin-keepassnatmsg

To upgrade KeePass Plugin KeePassNatMsg to the latest release version for enjoying the newest features, run the following command from the command line or from PowerShell:

choco upgrade keepass-plugin-keepassnatmsg

KeePassNatMsg on Linux and Mac

KeePass needs Mono. You can find detailed installation instructions on the official page of KeePass.

Configuration and Options

KeePassNatMsg works out-of-the-box. You don't have to explicitly configure it.

Settings in KeePassNatMsg options.

You can open the options dialog with menu: Tools > KeePassNatMsg Options

KeePassNatMsg Options Menu

The options dialog will appear:

KeePassNatMsg Options Dialog

General tab

  1. show a notification balloon whenever entries are delivered to the inquirer.
  2. returns only the best matching entries for the given url, otherwise all entries for a domain are send.
  1. if the active database in KeePass is locked, KeePassNatMsg sends a request to unlock the database. Now KeePass opens and the user has to enter the master password to unlock the database. Otherwise KeePassNatMsg tells the inquirer that the database is closed.
  2. expired entries are ignored if enabled.
  3. KeePassNatMsg returns only these entries which match the scheme of the given URL.
  1. sort found entries by username or title.
  2. removes all stored permissions in the entries of the currently selected database.
  3. Shows the status of the Native Messaging Host installations for the supported browsers, and the current Proxy version.
  4. Installs or Updates the Native Messaging Host, and updates the Proxy if an update is available.

KeePassNatMsg Options Advanced

Advanced tab

  1. KeePassNatMsg no longer asks for permissions to retrieve entries, it always allows access.
  2. KeePassNatMsg no longer asks for permission to update an entry, it always allows updating them.
  3. Choice of databases used for searches:
  1. When activated, it will search all string fields beginning with "URL".
  2. if activated KeePassNatMsg also search for string fields which are defined in the found entries and start with "KPH: " (note the space after colon). The string fields will be transferred to the client in alphabetical order. You can set string fields in the tab Advanced of an entry. <img src="https://raw.github.com/smorks/KeePassNatMsg/master/documentation/images/advanced-string-fields.png" alt="advanced tab of an entry" width="300px" />
  3. Override the version returned to KeePassXC-Browser
  4. When a database is selected, KeePassNatMsg will always use the selected database to search for entries.
  5. Use the same settings as KeePassXC. If checked, it will share all Allow/Deny lists and keys with KeePassXC.

KeePassNatMsg Options Keys

Keys Tab

Will display all configured browser keys, and you can remove them as needed.

Tips and Tricks

Support multiple URLs for one username + password

This is already implemented directly in KeePass.

  1. Open the context menu of an entry by clicking right on it and select Duplicate entry: <img src="https://raw.github.com/smorks/KeePassNatMsg/master/documentation/images/keepass-context-menu.png" alt="context-menu-entry" />

  2. Check the option to use references for username and password: <img src="https://raw.github.com/smorks/KeePassNatMsg/master/documentation/images/keepass-duplicate-entry-references.png" alt="mark checkbox references" width="300px" />

  3. You can change the title, URL and everything of the copied entry, but not the username and password. These fields contain a Reference Key which refers to the master entry you copied from.

TOTP Field Support

KeePassNatMsg can use the built-in TOTP support in KeePass (since KeePass v2.47, official docs).

KeePassNatMsg can also use the existence of either KeeOtp (otp) or KeeTrayTOTP (TOTP Seed) string fields to detect when TOTP entries should be returned in credential requests.

Troubleshooting

First: If an error occurs it will be shown as notification in system tray or as message box in KeePass.

Otherwise please check if it could be an error of the client you are using. For keepassxc-browser issues you can report an error here.

If you are having problems with KeePassNatMsg, please tell us at least the following information:

URL matching: How does it work?

KeePassNatMsg can receive 2 different URLs, called URL and SubmitURL.

CompareToUrl = SubmitURL if set, URL otherwise

For every entry, the Levenshtein Distance of his Entry-URL (or Title, if Entry-URL is not set) to the CompareToURL is calculated.

Only the Entries with the minimal distance are returned.

###Example: Submit-Url: http://www.host.com/subdomain1/login

Entry-URLDistance
http://www.host.com/16
http://www.host.com/subdomain16
http://www.host.com/subdomain27

Result: second entry is returned

Protocol