Skip to content
master
Switch branches/tags
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 

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

  • returns all matching entries for a given URL
  • updates entries
  • secure exchange of entries
  • notifies user if entries are delivered
  • user can allow or deny access to single entries
  • works only if the database is unlocked
  • request for unlocking the database if it is locked while connecting
  • searches in all opened databases (if user activates this feature)
  • Whenever events occur, the user is prompted either by tray notification or requesting interaction (allow/deny/remember).

System requirements

  • KeePass 2.17 or higher
  • For Windows: .NET Framework 4.0 or higher
  • For Linux: Mono 4.0 or higher
  • For Mac: Mono 4.0 or higher (untested)

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)
  • Tips to run KeePassNatMsg on lastest KeePass 2.31: install packages sudo apt-get install libmono-system-xml-linq4.0-cil libmono-system-data-datasetextensions4.0-cil libmono-system-runtime-serialization4.0-cil mono-mcs
  1. Restart KeePass
  2. Go to Tools -> KeePassNatMsg Options
  3. Click on "Install/Update Native Messaging Host", wait for message telling you it was intalled.
  4. Install the KeePassXC-Browser extension for your browser, and Connect to the database from within the extension.

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.

  • KeePassNatMsg stores shared public keys in "KeePassNatMsg Settings" in the root group of a password database.
  • Password entries saved by KeePassNatMsg are stored in a new group named "KeePassNatMsg Passwords" within the password database.
  • Remembered Allow/Deny settings are stored as JSON in custom string fields within the individual password entry in the database.

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.
  • given URL: https://example.org --> scheme: https:// --> only entries whose URL starts with https://
  1. sort found entries by username or title.
  2. removes all shared encryption-keys which are stored in the currently selected database. Every inquirer has to reauthenticate.
  3. removes all stored permissions in the entries of the currently selected database.
  4. Shows the status of the Native Messaging Host installations for the supported browsers, and the current Proxy version.
  5. 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. Searching for entries is no longer restricted to the current active database in KeePass but is extended to all opened databases!
  • Important: Even if another database is not connected with the inquirer, KeePassNatMsg will search and retrieve entries of all opened databases if the active one is connected to KeePassNatMsg!
  1. 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 transfered to the client in alphabetical order. You can set string fields in the tab Advanced of an entry.
    advanced tab of an entry

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:
    context-menu-entry

  2. Check the option to use references for username and password:
    mark checkbox references

  3. You can change the title, URL and evertything 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.

Troubleshooting

First: If an error occures 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:

  • operating system & version
  • version of KeePass
  • version of KeePassNatMsg
  • error message (if available)
  • used clients and their versions
  • URLs on which the problem occur (if available)

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-URL Distance
http://www.host.com/ 16
http://www.host.com/subdomain1 6
http://www.host.com/subdomain2 7

Result: second entry is returned

Protocol

View detailed protocol information.

About

KeePass plugin to expose credentials securely to a browser using Native Messaging

Resources

License

Packages

No packages published

Languages