Plugin Development How to develop plugins for KeePass 2.x.

This documentation applies to KeePass 2.x plugins. 2.x plugins are fundamentally different from 1.x plugins. 1.x plugins cannot be loaded by KeePass 2.x.

• Requirements
• Step-by-Step Tutorial
• Common Operations
• Plugin Conventions
• Can KeePass 2.x Plugins be written in Unmanaged C++?

  Requirements

Before you can start developing a KeePass plugin, you need the following prerequisites:

• Latest KeePass source code package. You can get it from the KeePass homepage.
• A C# 2.0 development IDE (Microsoft Visual Studio 2005, SharpDevelop or any other IDE).

  Step-by-Step Tutorial

Start your favorite IDE and create a new C# Class Library project. In this tutorial the example plugin we're developing is called SamplePlugin. The first thing you need to do now is to add a reference to KeePass: go to the references dialog and select the KeePass.exe file. After you added the reference, the namespaces KeePass and KeePassLib should be available.

KeePass plugins all need to derive from a base KeePass plugin class (Plugin in the KeePass.Plugins namespace). By overriding methods of this class, you can customize the behaviour of your plugin.

A minimal plugin looks like this:

using System;
using System.Collections.Generic;

using KeePass.Plugins;

namespace SamplePlugin
{
	public sealed class SamplePluginExt : Plugin
	{
		private IPluginHost m_host = null;

		public override bool Initialize(IPluginHost host)
		{
			m_host = host;
			return true;
		}
	}
}

You can find a fully documented and extended version of this simple plugin on the KeePass plugins web page.

This plugin does exactly nothing, but it shows some important conventions already, which must be followed by all plugins:

• The namespace must be named like the DLL file without extension. Our DLL file is named SamplePlugin.dll, therefore the namespace must be called SamplePlugin.
• The main plugin class (which KeePass will instanciate when it loads your plugin) must be called exactly the same as the namespace plus "Ext". In this case: "SamplePlugin" + "Ext" = "SamplePluginExt".
• The main plugin class must be derived from the KeePass.Plugins.Plugin base class.

The Initialize function is the most important one and you probably will always override it. In this function, you get an interface to the KeePass internals: an IPluginHost interface reference. By using this interface, you can access the KeePass main menu, the currently opened database, etc. The Initialize function is called immediately after KeePass loads your plugin. All initialization should be done in this function (not in the constructor of your plugin class!). If you successfully initialized everything, you must return true. If you return false, KeePass will immediately unload your plugin.

A second function that you will need very often is the Terminate function:

public override void Terminate()
{
}

This function is called shortly before KeePass unloads your plugin. You cannot abort this process (it's just a notification and your last chance to clean up all used resources, etc.). Immediately after you return from this function, KeePass can unload your plugin. It is highly recommended to free all resources in this function (not in the destructor of your plugin class!).

We're almost done! We now need to tell KeePass that our file is a KeePass plugin. This is done by editing the Version Information Block of the file. Open the file version editing dialog (in Visual Studio 2005: right-click onto the project name - 'Properties' - button 'Assembly Information'). All fields can be assigned freely except the Product Name field (for more information see Plugin Conventions). This field must be set to "KeePass Plugin" (without the quotes).

Now the last step: signing your assembly. Because KeePass is a strong-named assembly, your plugin must have a strong name, too. Go to the project options of your plugin and open the Signing tab. Enable assembly signing and generate a new key pair.

That's it already! Now try to compile your plugin and copy the resulting DLL file into the KeePass directory. If you start KeePass and go to the plugins dialog, you should see your plugin in the list of loaded plugins!

  Common Operations

Adding Menu Items:

Very often you want to add some menu items for your plugin. When clicked by the user, your plugin should get some notification. This can be done like follows. First of all you need to get a reference to the KeePass main menu or one of the special submenus (like Import, Tools, etc.). For this you can use the IPluginHost interface, which you received in the Initialize function. Then you can use standard tool strip operations to add a new menu item for your plugin. A very simple example, which adds a menu item to the Tools menu:

private ToolStripSeparator m_tsSeparator = null;
private ToolStripMenuItem m_tsmiMenuItem = null;

public override bool Initialize(IPluginHost host)
{
	m_host = host;

	// Get a reference to the 'Tools' menu item container
	ToolStripItemCollection tsMenu = m_host.MainWindow.ToolsMenu.DropDownItems;

	// Add a separator at the bottom
	m_tsSeparator = new ToolStripSeparator();
	tsMenu.Add(m_tsSeparator);

	// Add menu item 'Do Something'
	m_tsmiMenuItem = new ToolStripMenuItem();
	m_tsmiMenuItem.Text = "Do Something";
	m_tsmiMenuItem.Click += OnMenuDoSomething;
	tsMenu.Add(m_tsmiMenuItem);
}

public override void Terminate()
{
	// Remove all of our menu items
	ToolStripItemCollection tsMenu = m_host.MainWindow.ToolsMenu.DropDownItems;
	tsMenu.Remove(m_tsSeparator);
	tsMenu.Remove(m_tsmiMenuItem);
}

private void OnMenuDoSomething(object sender, EventArgs e)
{
	// Called when the menu item is clicked
}

If you are working with tool strips, you of course have to add a reference to System.Windows.Forms of the .NET framework.

It is highly recommended that you remove all menu items created by your plugin in the Terminate function (as shown in the example above). After the Terminate function has been called, everything should look like before loading your plugin.

In the example, we created a separator and one menu item. To this menu item an event handler for the Click event is attached. There's nothing special, this is all standard Windows.Forms stuff.

For examples of adding popup menus, see the SamplePlugin in the KeePass source code distribution.

Adding Groups and Entries:

For this, see the sample plugin and the KeePassLib documentation.

  Plugin Conventions

File Version Information Block:

KeePass uses the file version information block to detect if a DLL file is a KeePass plugin and retrieves information from it to show in the plugins dialog. The fields are used as follows:

• Title: Should contain the full name of the plugin.
• Description: Should contain a short description (not more than 5 lines) of your plugin.
• Company: Should contain the author name of the plugin.
• Product Name: Must be set to "KeePass Plugin" (without the quotes).
• Copyright: Not used by KeePass; freely assignable by the plugin.
• Trademarks: Not used by KeePass; freely assignable by the plugin.
• Assembly Version: Should be set to the recommended KeePass version (i.e. the KeePass version your plugin is built for).
• File Version: Should be set to the version of your plugin. It is up to you how you are versioning your plugin builds, but it should be a scheme that allows version comparisons (based on string comparisons).
• GUID: Not used by KeePass; freely assignable by the plugin.

Namespace and Class Naming:

The namespace must be named like the DLL file without extension. For example, if the DLL file is named SecretImporter.dll, you must call the namespace SecretImporter.

The plugin class must be named like the namespace plus "Ext". For the SecretImporter plugin, this would be SecretImporterExt.

  Can KeePass 2.x Plugins be written in Unmanaged C++?

Yes and no. You can write the complete logic of your plugin in unmanaged C++ (native Win32 APIs can be used). Anyway you must provide a managed interface to your plugin, i.e. you must export a managed class derived from the Plugin base class as described in the step-by-step tutorial.

Also, managed C++ will be required to modify the KeePass internals (i.e. entries, groups, main window, ...).

For an example how to use unmanaged APIs in a managed C++ plugin assembly, see the SamplePluginCpp project in the KeePass source distribution (directory Plugins).